@typescript-eslint/eslint-plugin 8.25.1-alpha.17 → 8.25.1-alpha.18

package/dist/rules/unified-signatures.d.ts

@@ -2,6 +2,7 @@ export type MessageIds = 'omittingRestParameter' | 'omittingSingleParameter' | '
 export type Options = [
     {
         ignoreDifferentlyNamedParameters?: boolean;
+        ignoreOverloadsWithDifferentJSDoc?: boolean;
     }
 ];
 declare const _default: import("@typescript-eslint/utils/ts-eslint").RuleModule<MessageIds, Options, import("../../rules").ESLintPluginDocs, import("@typescript-eslint/utils/ts-eslint").RuleListener>;

package/dist/rules/unified-signatures.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"unified-signatures.d.ts","sourceRoot":"","sources":["../../src/rules/unified-signatures.ts"],"names":[],"mappings":"AAuDA,MAAM,MAAM,UAAU,GAClB,uBAAuB,GACvB,yBAAyB,GACzB,2BAA2B,CAAC;AAEhC,MAAM,MAAM,OAAO,GAAG;IACpB;QACE,gCAAgC,CAAC,EAAE,OAAO,CAAC;KAC5C;CACF,CAAC;;AAEF,wBA2gBG"}
+{"version":3,"file":"unified-signatures.d.ts","sourceRoot":"","sources":["../../src/rules/unified-signatures.ts"],"names":[],"mappings":"AAuDA,MAAM,MAAM,UAAU,GAClB,uBAAuB,GACvB,yBAAyB,GACzB,2BAA2B,CAAC;AAEhC,MAAM,MAAM,OAAO,GAAG;IACpB;QACE,gCAAgC,CAAC,EAAE,OAAO,CAAC;QAC3C,iCAAiC,CAAC,EAAE,OAAO,CAAC;KAC7C;CACF,CAAC;;AAEF,wBAyiBG"}

package/dist/rules/unified-signatures.js

@@ -25,6 +25,10 @@ exports.default = (0, util_1.createRule)({
                         type: 'boolean',
                         description: 'Whether two parameters with different names at the same index should be considered different even if their types are the same.',
                     },
+                    ignoreOverloadsWithDifferentJSDoc: {
+                        type: 'boolean',
+                        description: 'Whether two overloads with different JSDoc comments should be considered different even if their parameter and return types are the same.',
+                    },
                 },
             },
         ],
@@ -32,9 +36,10 @@ exports.default = (0, util_1.createRule)({
     defaultOptions: [
         {
             ignoreDifferentlyNamedParameters: false,
+            ignoreOverloadsWithDifferentJSDoc: false,
         },
     ],
-    create(context, [{ ignoreDifferentlyNamedParameters }]) {
+    create(context, [{ ignoreDifferentlyNamedParameters, ignoreOverloadsWithDifferentJSDoc }]) {
         //----------------------------------------------------------------------
         // Helpers
         //----------------------------------------------------------------------
@@ -126,6 +131,13 @@ exports.default = (0, util_1.createRule)({
                     }
                 }
             }
+            if (ignoreOverloadsWithDifferentJSDoc) {
+                const aComment = getBlockCommentForNode(getExportingNode(a) ?? a);
+                const bComment = getBlockCommentForNode(getExportingNode(b) ?? b);
+                if (aComment?.value !== bComment?.value) {
+                    return false;
+                }
+            }
             return (typesAreEqual(a.returnType, b.returnType) &&
                 // Must take the same type parameters.
                 // If one uses a type parameter (from outside) and the other doesn't, they shouldn't be joined.
@@ -306,6 +318,15 @@ exports.default = (0, util_1.createRule)({
             addFailures(failures);
             currentScope = scopes.pop();
         }
+        /**
+         * @returns the first valid JSDoc comment annotating `node`
+         */
+        function getBlockCommentForNode(node) {
+            return context.sourceCode
+                .getCommentsBefore(node)
+                .reverse()
+                .find(comment => comment.type === utils_1.AST_TOKEN_TYPES.Block);
+        }
         function addOverload(signature, key, containingNode) {
             key ??= getOverloadKey(signature);
             if (currentScope &&

package/docs/rules/unified-signatures.mdx

@@ -78,6 +78,50 @@ function f(b: string): void;
 </TabItem>
 </Tabs>
 
+### `ignoreOverloadsWithDifferentJSDoc`
+
+{/* insert option description */}
+
+Examples of code for this rule with `ignoreOverloadsWithDifferentJSDoc`:
+
+<Tabs>
+<TabItem value="❌ Incorrect">
+
+```ts option='{ "ignoreOverloadsWithDifferentJSDoc": true }'
+declare function f(x: string): void;
+declare function f(x: boolean): void;
+/**
+ * @deprecate
+ */
+declare function f(x: number): void;
+/**
+ * @deprecate
+ */
+declare function f(x: null): void;
+```
+
+</TabItem>
+<TabItem value="✅ Correct">
+
+```ts option='{ "ignoreOverloadsWithDifferentJSDoc": true }'
+declare function f(x: string): void;
+/**
+ * This signature does something else.
+ */
+declare function f(x: boolean): void;
+/**
+ * @async
+ */
+declare function f(x: number): void;
+/**
+ * @deprecate
+ */
+declare function f(x: null): void;
+```
+
+</TabItem>
+</Tabs>
+
 ## When Not To Use It
 
 This is purely a stylistic rule to help with readability of function signature overloads.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typescript-eslint/eslint-plugin",
-  "version": "8.25.1-alpha.17",
+  "version": "8.25.1-alpha.18",
   "description": "TypeScript plugin for ESLint",
   "files": [
     "dist",
@@ -62,10 +62,10 @@
   },
   "dependencies": {
     "@eslint-community/regexpp": "^4.10.0",
-    "@typescript-eslint/scope-manager": "8.25.1-alpha.17",
-    "@typescript-eslint/type-utils": "8.25.1-alpha.17",
-    "@typescript-eslint/utils": "8.25.1-alpha.17",
-    "@typescript-eslint/visitor-keys": "8.25.1-alpha.17",
+    "@typescript-eslint/scope-manager": "8.25.1-alpha.18",
+    "@typescript-eslint/type-utils": "8.25.1-alpha.18",
+    "@typescript-eslint/utils": "8.25.1-alpha.18",
+    "@typescript-eslint/visitor-keys": "8.25.1-alpha.18",
     "graphemer": "^1.4.0",
     "ignore": "^5.3.1",
     "natural-compare": "^1.4.0",
@@ -76,8 +76,8 @@
     "@types/marked": "^5.0.2",
     "@types/mdast": "^4.0.3",
     "@types/natural-compare": "*",
-    "@typescript-eslint/rule-schema-to-typescript-types": "8.25.1-alpha.17",
-    "@typescript-eslint/rule-tester": "8.25.1-alpha.17",
+    "@typescript-eslint/rule-schema-to-typescript-types": "8.25.1-alpha.18",
+    "@typescript-eslint/rule-tester": "8.25.1-alpha.18",
     "ajv": "^6.12.6",
     "cross-env": "^7.0.3",
     "cross-fetch": "*",