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

package/dist/rules/explicit-module-boundary-types.d.ts

@@ -5,6 +5,7 @@ export type Options = [
         allowedNames?: string[];
         allowHigherOrderFunctions?: boolean;
         allowTypedFunctionExpressions?: boolean;
+        allowOverloadFunctions?: boolean;
     }
 ];
 export type MessageIds = 'anyTypedArg' | 'anyTypedArgUnnamed' | 'missingArgType' | 'missingArgTypeUnnamed' | 'missingReturnType';

package/dist/rules/explicit-module-boundary-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"explicit-module-boundary-types.d.ts","sourceRoot":"","sources":["../../src/rules/explicit-module-boundary-types.ts"],"names":[],"mappings":"AAoBA,MAAM,MAAM,OAAO,GAAG;IACpB;QACE,kCAAkC,CAAC,EAAE,OAAO,CAAC;QAC7C,yCAAyC,CAAC,EAAE,OAAO,CAAC;QACpD,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;QACxB,yBAAyB,CAAC,EAAE,OAAO,CAAC;QACpC,6BAA6B,CAAC,EAAE,OAAO,CAAC;KACzC;CACF,CAAC;AACF,MAAM,MAAM,UAAU,GAClB,aAAa,GACb,oBAAoB,GACpB,gBAAgB,GAChB,uBAAuB,GACvB,mBAAmB,CAAC;;AAExB,wBAmdG"}
+{"version":3,"file":"explicit-module-boundary-types.d.ts","sourceRoot":"","sources":["../../src/rules/explicit-module-boundary-types.ts"],"names":[],"mappings":"AAyBA,MAAM,MAAM,OAAO,GAAG;IACpB;QACE,kCAAkC,CAAC,EAAE,OAAO,CAAC;QAC7C,yCAAyC,CAAC,EAAE,OAAO,CAAC;QACpD,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;QACxB,yBAAyB,CAAC,EAAE,OAAO,CAAC;QACpC,6BAA6B,CAAC,EAAE,OAAO,CAAC;QACxC,sBAAsB,CAAC,EAAE,OAAO,CAAC;KAClC;CACF,CAAC;AACF,MAAM,MAAM,UAAU,GAClB,aAAa,GACb,oBAAoB,GACpB,gBAAgB,GAChB,uBAAuB,GACvB,mBAAmB,CAAC;;AAExB,wBAweG"}

package/dist/rules/explicit-module-boundary-types.js

@@ -48,6 +48,10 @@ exports.default = (0, util_1.createRule)({
                             'You must still type the parameters of the function.',
                         ].join('\n'),
                     },
+                    allowOverloadFunctions: {
+                        type: 'boolean',
+                        description: 'Whether to ignore return type annotations on functions with overload signatures.',
+                    },
                     allowTypedFunctionExpressions: {
                         type: 'boolean',
                         description: 'Whether to ignore type annotations on the variable of a function expression.',
@@ -62,6 +66,7 @@ exports.default = (0, util_1.createRule)({
             allowDirectConstAssertionInArrowFunctions: true,
             allowedNames: [],
             allowHigherOrderFunctions: true,
+            allowOverloadFunctions: false,
             allowTypedFunctionExpressions: true,
         },
     ],
@@ -342,6 +347,11 @@ exports.default = (0, util_1.createRule)({
                 (0, explicitReturnTypeUtils_1.ancestorHasReturnType)(node)) {
                 return;
             }
+            if (options.allowOverloadFunctions &&
+                node.parent.type === utils_1.AST_NODE_TYPES.MethodDefinition &&
+                (0, util_1.hasOverloadSignatures)(node.parent, context)) {
+                return;
+            }
             (0, explicitReturnTypeUtils_1.checkFunctionExpressionReturnType)({ node, returns }, options, context.sourceCode, loc => {
                 context.report({
                     loc,
@@ -359,6 +369,10 @@ exports.default = (0, util_1.createRule)({
             if (isAllowedName(node) || (0, explicitReturnTypeUtils_1.ancestorHasReturnType)(node)) {
                 return;
             }
+            if (options.allowOverloadFunctions &&
+                (0, util_1.hasOverloadSignatures)(node, context)) {
+                return;
+            }
             (0, explicitReturnTypeUtils_1.checkFunctionReturnType)({ node, returns }, options, context.sourceCode, loc => {
                 context.report({
                     loc,

package/dist/rules/no-unnecessary-type-assertion.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"no-unnecessary-type-assertion.d.ts","sourceRoot":"","sources":["../../src/rules/no-unnecessary-type-assertion.ts"],"names":[],"mappings":"AAqBA,MAAM,MAAM,OAAO,GAAG;IACpB;QACE,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;KAC1B;CACF,CAAC;AACF,MAAM,MAAM,UAAU,GAAG,yBAAyB,GAAG,sBAAsB,CAAC;;AAE5E,wBAiXG"}
+{"version":3,"file":"no-unnecessary-type-assertion.d.ts","sourceRoot":"","sources":["../../src/rules/no-unnecessary-type-assertion.ts"],"names":[],"mappings":"AAqBA,MAAM,MAAM,OAAO,GAAG;IACpB;QACE,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;KAC1B;CACF,CAAC;AACF,MAAM,MAAM,UAAU,GAAG,yBAAyB,GAAG,sBAAsB,CAAC;;AAE5E,wBAwXG"}

package/dist/rules/no-unnecessary-type-assertion.js

@@ -260,6 +260,10 @@ exports.default = (0, util_1.createRule)({
                     // so figure out if the variable is used in a place that accepts nullable types
                     const contextualType = (0, util_1.getContextualType)(checker, originalNode);
                     if (contextualType) {
+                        if ((0, util_1.isTypeFlagSet)(type, ts.TypeFlags.Unknown) &&
+                            !(0, util_1.isTypeFlagSet)(contextualType, ts.TypeFlags.Unknown)) {
+                            return;
+                        }
                         // in strict mode you can't assign null to undefined, so we have to make sure that
                         // the two types share a nullable type
                         const typeIncludesUndefined = (0, util_1.isTypeFlagSet)(type, ts.TypeFlags.Undefined);

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/explicit-module-boundary-types.mdx

@@ -260,6 +260,20 @@ export const foo: FooType = bar => {};
 </TabItem>
 </Tabs>
 
+### `allowOverloadFunctions`
+
+{/* insert option description */}
+
+Examples of correct code when `allowOverloadFunctions` is set to `true`:
+
+```ts option='{ "allowOverloadFunctions": true }' showPlaygroundButton
+export function test(a: string): string;
+export function test(a: number): number;
+export function test(a: unknown) {
+  return a;
+}
+```
+
 ## When Not To Use It
 
 If your project is not used by downstream consumers that are sensitive to API types, you can disable this rule.

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.16",
+  "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.16",
-    "@typescript-eslint/type-utils": "8.25.1-alpha.16",
-    "@typescript-eslint/utils": "8.25.1-alpha.16",
-    "@typescript-eslint/visitor-keys": "8.25.1-alpha.16",
+    "@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.16",
-    "@typescript-eslint/rule-tester": "8.25.1-alpha.16",
+    "@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": "*",