Add MissingExportEquals problem

Author: andrewbranch

docs/problems/MissingExportEquals.md

@@ -0,0 +1,77 @@
+# ❓ Missing `export =`
+
+The JavaScript appears to set both `module.exports` and `module.exports.default` for improved compatibility, but the types only reflect the latter (by using `export default`). This will cause TypeScript under the `node16` module mode to think an extra `.default` property access is required, which will work at runtime but is not necessary. These types `export =` an object with a `default` property instead of using `export default`.
+
+## Explanation
+
+This problem occurs when a CommonJS JavaScript file appears to use a compatibility pattern like:
+
+```js
+class Whatever {
+  /* ... */
+}
+Whatever.default = Whatever;
+module.exports = Whatever;
+```
+
+but the corresponding type definitions only reflect the existence of the `module.exports.default` property:
+
+```ts
+declare class Whatever {
+  /* ... */
+}
+export default Whatever;
+```
+
+The types should declare the existence of the `Whatever` class on both `module.exports` and `module.exports.default`. The method of doing this can vary depending on the kinds of things already being exported from the types. When the `export default` exports a class, and that class is the only export in the file, the `default` can be declared as a static property on the class, and the `export default` swapped for `export =`:
+
+```ts
+declare class Whatever {
+  static default: typeof Whatever;
+  /* ... */
+}
+export = Whatever;
+```
+
+When the file exports additional types, it will be necessary to declare a `namespace` that merges with the class and contains the exported types:
+
+```ts
+declare class Whatever {
+  static default: typeof Whatever;
+  /* ... */
+}
+declare namespace Whatever {
+  export interface WhateverProps {
+    /* ... */
+  }
+}
+export = Whatever;
+```
+
+This merging namespace can also be used to declare the `default` property when the main export is a function:
+
+```ts
+declare function Whatever(props: Whatever.WhateverProps): void;
+declare namespace Whatever {
+  declare const _default: typeof Whatever;
+  export { _default as default };
+
+  export interface WhateverProps {
+    /* ... */
+  }
+}
+export = Whatever;
+```
+
+## Consequences
+
+This problem is similar to the [“Incorrect default export”](./FalseExportDefault.md) problem, but in this case, the types are _incomplete_ rather than wholly incorrect. This incompleteness may lead TypeScript users importing from Node.js ESM code to add an extra `.default` property onto default imports to access the module’s `module.exports.default` property, even though accessing the `module.exports` would have been sufficient.
+
+```ts
+import Whatever from "pkg";
+Whatever.default(); // Ok, but `Whatever()` would have worked!
+```
+
+## Common causes
+
+This problem is usually caused by library authors incorrectly hand-authoring declaration files to match existing JavaScript rather than generating JavaScript and type declarations from TypeScript with `tsc`, or by using a third-party TypeScript emitter that adds an extra compatibility layer to TypeScript written with `export default`. Libraries compiling to CommonJS should generally avoid writing `export default` as input syntax.

packages/core/src/checks/entrypointResolutionProblems.ts

@@ -87,27 +87,35 @@ export function getEntrypointResolutionProblems(
         if (
           typesExports.has(ts.InternalSymbolName.Default) &&
           !typesExports.has(ts.InternalSymbolName.ExportEquals) &&
-          jsExports.has(ts.InternalSymbolName.ExportEquals) &&
-          !jsExports.has(ts.InternalSymbolName.Default)
+          jsExports.has(ts.InternalSymbolName.ExportEquals)
         ) {
-          const jsChecker = host
-            .createProgram([implementationResolution.fileName], {
-              allowJs: true,
-              checkJs: true,
-            })
-            .getTypeChecker();
-          // Check for `default` property on `jsModule["export="]`
-          if (
-            !jsChecker
-              .getExportsAndPropertiesOfModule(jsChecker.resolveExternalModuleSymbol(jsSourceFile.symbol))
-              .some((s) => s.name === "default")
-          ) {
-            problems.push({
-              kind: "FalseExportDefault",
-              entrypoint: subpath,
-              resolutionKind,
-            });
+          if (!jsExports.has(ts.InternalSymbolName.Default)) {
+            const jsChecker = host
+              .createProgram([implementationResolution.fileName], {
+                allowJs: true,
+                checkJs: true,
+              })
+              .getTypeChecker();
+            // Check for `default` property on `jsModule["export="]`
+            if (
+              !jsChecker
+                .getExportsAndPropertiesOfModule(jsChecker.resolveExternalModuleSymbol(jsSourceFile.symbol))
+                .some((s) => s.name === "default")
+            ) {
+              problems.push({
+                kind: "FalseExportDefault",
+                entrypoint: subpath,
+                resolutionKind,
+              });
+              return;
+            }
           }
+          // types have a default, JS has a default and a module.exports =
+          problems.push({
+            kind: "MissingExportEquals",
+            entrypoint: subpath,
+            resolutionKind,
+          });
         }
       }
     }

packages/core/src/problems.ts

@@ -18,7 +18,7 @@ export interface ProblemKindInfo {
 
 export const problemKindInfo: Record<ProblemKind, ProblemKindInfo> = {
   Wildcard: {
-    emoji: "❓",
+    emoji: "🃏",
     title: "Wildcards",
     shortDescription: "Unable to check",
     description: "Wildcard subpaths cannot yet be analyzed by this tool.",
@@ -89,6 +89,15 @@ export const problemKindInfo: Record<ProblemKind, ProblemKindInfo> = {
     docsUrl:
       "https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/docs/problems/FalseExportDefault.md",
   },
+  MissingExportEquals: {
+    emoji: "❓",
+    title: "Types are missing an `export =`",
+    shortDescription: "Missing `export =`",
+    description:
+      "The JavaScript appears to set both `module.exports` and `module.exports.default` for improved compatibility, but the types only reflect the latter (by using `export default`). This will cause TypeScript under the `node16` module mode to think an extra `.default` property access is required, which will work at runtime but is not necessary. These types `export =` an object with a `default` property instead of using `export default`.",
+    docsUrl:
+      "https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/docs/problems/MissingExportEquals.md",
+  },
   UnexpectedModuleSyntax: {
     emoji: "🚭",
     title: "Syntax is incompatible with detected module kind",

packages/core/src/types.ts

@@ -84,7 +84,8 @@ export type EntrypointResolutionProblemKind =
   | "CJSResolvesToESM"
   | "Wildcard"
   | "FallbackCondition"
-  | "FalseExportDefault";
+  | "FalseExportDefault"
+  | "MissingExportEquals";
 
 export interface EntrypointResolutionProblem {
   kind: EntrypointResolutionProblemKind;

packages/core/src/utils.ts

@@ -102,6 +102,7 @@ export function isEntrypointResolutionProblemKind(kind: ProblemKind): kind is En
     case "Wildcard":
     case "FallbackCondition":
     case "FalseExportDefault":
+    case "MissingExportEquals":
       return true;
     default:
       return false as AssertNever<typeof kind & EntrypointResolutionProblem["kind"]>;

packages/core/test/fixtures/[email protected]

@@ -321,6 +321,16 @@
     }
   },
   "problems": [
+    {
+      "kind": "MissingExportEquals",
+      "entrypoint": ".",
+      "resolutionKind": "node10"
+    },
+    {
+      "kind": "MissingExportEquals",
+      "entrypoint": ".",
+      "resolutionKind": "node16-cjs"
+    },
     {
       "kind": "FalseCJS",
       "entrypoint": ".",

packages/core/test/fixtures/[email protected]

@@ -500,5 +500,26 @@
       "isWildcard": false
     }
   },
-  "problems": []
+  "problems": [
+    {
+      "kind": "MissingExportEquals",
+      "entrypoint": ".",
+      "resolutionKind": "node10"
+    },
+    {
+      "kind": "MissingExportEquals",
+      "entrypoint": ".",
+      "resolutionKind": "node16-cjs"
+    },
+    {
+      "kind": "MissingExportEquals",
+      "entrypoint": ".",
+      "resolutionKind": "node16-esm"
+    },
+    {
+      "kind": "MissingExportEquals",
+      "entrypoint": ".",
+      "resolutionKind": "bundler"
+    }
+  ]
 }