feat(eslint-plugin): add explicit-module-boundary-types rule (#65)

This rule will deprecate no-untyped-public-signatures, as it covers the same functionality but checks exported functions in additio
n to class methods.

packages/eslint-plugin/README.md

@@ -107,6 +107,7 @@ Pro Tip: For larger codebases you may want to consider splitting our linting int
 | [`@typescript-eslint/consistent-type-definitions`](./docs/rules/consistent-type-definitions.md)           | Consistent with type definition either `interface` or `type`                                                                                        |                    | :wrench: |                   |
 | [`@typescript-eslint/explicit-function-return-type`](./docs/rules/explicit-function-return-type.md)       | Require explicit return types on functions and class methods                                                                                        | :heavy_check_mark: |          |                   |
 | [`@typescript-eslint/explicit-member-accessibility`](./docs/rules/explicit-member-accessibility.md)       | Require explicit accessibility modifiers on class properties and methods                                                                            |                    |          |                   |
+| [`@typescript-eslint/explicit-module-boundary-types`](./docs/rules/explicit-module-boundary-types.md)     | Require explicit return types on exported functions' and classes' public class methods                                                      |                    |          |                   |
 | [`@typescript-eslint/func-call-spacing`](./docs/rules/func-call-spacing.md)                               | Require or disallow spacing between function identifiers and their invocations                                                                      |                    | :wrench: |                   |
 | [`@typescript-eslint/generic-type-naming`](./docs/rules/generic-type-naming.md)                           | Enforces naming of generic type variables                                                                                                           |                    |          |                   |
 | [`@typescript-eslint/indent`](./docs/rules/indent.md)                                                     | Enforce consistent indentation                                                                                                                      |                    | :wrench: |                   |

packages/eslint-plugin/docs/rules/explicit-module-boundary-types.md

@@ -0,0 +1,184 @@
+# Require explicit return type on exported functions' and classes' public class methods (explicit-module-boundary-types)
+
+Explicit types for function return values makes it clear to any calling code what is the module boundary's output.
+
+Consider using this rule in place of [`no-untyped-public-signature`](./no-untyped-public-signature.md) which has been deprecated.
+
+## Rule Details
+
+This rule aims to ensure that the values returned from a module are of the expected type.
+
+The following patterns are considered warnings:
+
+```ts
+// Should indicate that no value is returned (void)
+export function test() {
+  return;
+}
+
+// Should indicate that a number is returned
+export default function() {
+  return 1;
+}
+
+// Should indicate that a string is returned
+export var arrowFn = () => 'test';
+
+export class Test {
+  // Should indicate that no value is returned (void)
+  method() {
+    return;
+  }
+}
+```
+
+The following patterns are not warnings:
+
+```ts
+// Function is not exported
+function test() {
+  return;
+}
+
+// A return value of type number
+export var fn = function(): number {
+  return 1;
+};
+
+// A return value of type string
+export var arrowFn = (): string => 'test';
+
+// Class is not exported
+class Test {
+  method() {
+    return;
+  }
+}
+```
+
+## Options
+
+The rule accepts an options object with the following properties:
+
+```ts
+type Options = {
+  // if true, type annotations are also allowed on the variable of a function expression rather than on the function directly
+  allowTypedFunctionExpressions?: boolean;
+  // if true, functions immediately returning another function expression will not be checked
+  allowHigherOrderFunctions?: boolean;
+  // an array of function/method names that will not be checked
+  allowedNames?: string[];
+};
+
+const defaults = {
+  allowTypedFunctionExpressions: true,
+  allowHigherOrderFunctions: true,
+  allowedNames: [],
+};
+```
+
+### Configuring in a mixed JS/TS codebase
+
+If you are working on a codebase within which you lint non-TypeScript code (i.e. `.js`/`.jsx`), you should ensure that you should use [ESLint `overrides`](https://eslint.org/docs/user-guide/configuring#disabling-rules-only-for-a-group-of-files) to only enable the rule on `.ts`/`.tsx` files. If you don't, then you will get unfixable lint errors reported within `.js`/`.jsx` files.
+
+```jsonc
+{
+  "rules": {
+    // disable the rule for all files
+    "@typescript-eslint/explicit-module-boundary-types": "off"
+  },
+  "overrides": [
+    {
+      // enable the rule specifically for TypeScript files
+      "files": ["*.ts", "*.tsx"],
+      "rules": {
+        "@typescript-eslint/explicit-module-boundary-types": ["error"]
+      }
+    }
+  ]
+}
+```
+
+### `allowTypedFunctionExpressions`
+
+Examples of **incorrect** code for this rule with `{ allowTypedFunctionExpressions: true }`:
+
+```ts
+export let arrowFn = () => 'test';
+
+export let funcExpr = function() {
+  return 'test';
+};
+
+export let objectProp = {
+  foo: () => 1,
+};
+```
+
+Examples of additional **correct** code for this rule with `{ allowTypedFunctionExpressions: true }`:
+
+```ts
+type FuncType = () => string;
+
+export let arrowFn: FuncType = () => 'test';
+
+export let funcExpr: FuncType = function() {
+  return 'test';
+};
+
+export let asTyped = (() => '') as () => string;
+export let castTyped = <() => string>(() => '');
+
+interface ObjectType {
+  foo(): number;
+}
+export let objectProp: ObjectType = {
+  foo: () => 1,
+};
+export let objectPropAs = {
+  foo: () => 1,
+} as ObjectType;
+export let objectPropCast = <ObjectType>{
+  foo: () => 1,
+};
+```
+
+### `allowHigherOrderFunctions`
+
+Examples of **incorrect** code for this rule with `{ allowHigherOrderFunctions: true }`:
+
+```ts
+export var arrowFn = () => () => {};
+
+export function fn() {
+  return function() {};
+}
+```
+
+Examples of **correct** code for this rule with `{ allowHigherOrderFunctions: true }`:
+
+```ts
+export var arrowFn = () => (): void => {};
+
+export function fn() {
+  return function(): void {};
+}
+```
+
+### `allowedName`
+
+You may pass function/method names you would like this rule to ignore, like so:
+
+```cjson
+{
+    "@typescript-eslint/explicit-module-boundary-types": ["error", { "allowedName": ["ignoredFunctionName", "ignoredMethodName"] }]
+}
+```
+
+## When Not To Use It
+
+If you wish to make sure all functions have explicit return types, as opposed to only the module boundaries, you can use [explicit-function-return-type](https://github.com/eslint/eslint/blob/master/docs/rules/explicit-function-return-type.md)
+
+## Further Reading
+
+- TypeScript [Functions](https://www.typescriptlang.org/docs/handbook/functions.html#function-types)

packages/eslint-plugin/src/configs/all.json

@@ -15,6 +15,7 @@
     "@typescript-eslint/consistent-type-definitions": "error",
     "@typescript-eslint/explicit-function-return-type": "error",
     "@typescript-eslint/explicit-member-accessibility": "error",
+    "@typescript-eslint/explicit-module-boundary-types": "error",
     "func-call-spacing": "off",
     "@typescript-eslint/func-call-spacing": "error",
     "@typescript-eslint/generic-type-naming": "error",