Add docs for each problem kind (arethetypeswrong#41)

* Docs WIP

* Finish InternalResolutionError

* Link to new docs in README, website, and CLI

* Add changeset

Author: andrewbranch

.changeset/happy-deers-marry.md

@@ -0,0 +1,6 @@
+---
+"@arethetypeswrong/core": minor
+"@arethetypeswrong/cli": minor
+---
+
+Added links to new documentation for each problem kind

README.md

@@ -1,50 +1,18 @@
 # [arethetypeswrong.github.io](https://arethetypeswrong.github.io)
 
-This project attempts to analyze npm package contents for issues with their TypeScript types, particularly ESM-related module resolution issues. Currently, the following kinds of problems can be detected in the `node10`, `node16`, and `bundler` module resolution modes:
-
-- **The package doesn’t ship types.** In the future, the tool may pull typings from DefinitelyTyped and check for agreement ([dts-critic](https://github.com/microsoft/DefinitelyTyped-tools/tree/master/packages/dts-critic) is prior art).
-- **Resolution failed.** Occurs when an import of the package (or a package subpath defined in its package.json `exports`) fails to resolve completely. This will result in a TypeScript compiler error, and may indicate that the runtime corresponding to the module resolution mode tested might fail to resolve it too.
-- **Untyped resolution.** Occurs when TypeScript can resolve a JavaScript file, but no type declaration file. This is a TypeScript compiler error under `noImplicitAny`.
-- **Types are CJS, but implementation is ESM.** In the `node16` resolution mode, TypeScript detects whether Node itself will assume a file is a CommonJS or ECMAScript module. If the types resolved are detected to be CJS, but the JavaScript resolved is detected to be ESM, this problem is raised. It is often caused by a dependency’s package.json doing something like:
-  ```json
-  {
-    "exports": {
-      "types": "./index.d.ts",
-      "import": "./index.mjs",
-      "require": "./index.js"
-    }
-  }
-  ```
-  Because there is no `"type": "module"` setting here, the `.js` and `.d.ts` file will always be interpreted as a CommonJS module. But if the _importing_ file is an ES module, the runtime will resolve to the `.mjs` file, which is unambiguously ESM. In this case, the module kind of the types misrepresents the runtime-resolved module. This tends to present the most issues for users when default exports are used. In the future, this tool may detect whether an `export default` might make this problem more severe and give a full explanation of why. In the meantime, you can read the explanation in [this issue](https://github.com/microsoft/TypeScript/issues/50058#issuecomment-1404411380). The simple fix for the example above would be to add an `index.d.mts` file dedicated to typing the `.mjs` module, and remove the `"types"` condition.
-- **Types are ESM, but implementation is CJS.** The reverse of the above, but with worse consequences. Because a CommonJS module cannot access an ES module without (async) dynamic import, this kind of mismatch means that TypeScript will _falsely_ belive that a CJS module is unable to import the package without dynamic import. This is more rare, but can happen with a similar situation as the above, but where the package.json has `"type": "module"`, and the importing file is a CJS module.
-- **Syntax is incompatible with detected module kind.** In Node, as well as in some bundlers, whether a file should be interpreted as CJS or ESM is a pure function of the file extension and the nearest ancestor package.json `type`. If these signal that the file is ESM, `module` and `require` will be `undefined`. If they signal that the file is CJS, `import` and `export` statements will be syntax errors. This problem is raised when syntax incompatible with the detected module kind is used.
-- **Package (or subpath) is ESM-only.** This occurs when a CommonJS importing module in `node16` resolves to an ES module (and not falsely so, as above, as far as we can tell). This is a TypeScript compiler error and will be a runtime error in Node. It’s not necessarily a defect of the package; it likely just means that the author decided to only publish ESM, leaving their CommonJS consumers without a good option.
-- **Resolved through a fallback condition.** In Node, when resolution of an import path hits conditional `"exports"` in a package.json, it tries to resolve with the first matching condition. If resolution fails with that condition, the process is over and the import is not resolved. TypeScript’s algorithm instead continues through the list of conditions and attempts to resolve with any other condition that matches, until resolution succeeds or the no more conditions match. This is [a TypeScript bug](https://github.com/microsoft/TypeScript/issues/50762), so its behavior should not be relied upon—even if the bug never gets fixed, results that arise from it are likely to be innacurate since the resolution process diverges from Node.
-- **CJS module uses a default export.** CommonJS files can indicate to bundlers that a default import should resolve to its `module.exports.default` instead of its `module.exports` by setting `module.exports.__esModule` to `true`. Node does not respect the `__esModule` marker, though, so default imports of the file in Node will have to add an additional `.default` property access in order to get to the file’s intended default export:
-  ```ts
-  // main.mts:
-  import doSomething from "dependency";
-  doSomething(); // doesn't work
-  doSomething.default(); // works
-  ```
-  This problem is reported when a CJS module appears to use `module.exports.default`, has an `__esModule` marker, and its types use `export default`. It’s important to notice that in this case, the types and the implementation agree. Adding a `.default` is necessary, both to run in Node and to satisfy the TypeScript compiler. There are no inconsistencies here, but the pattern is discouraged since the code needed to use the import in a bundler and the code needed in Node are mutually incompatible. Instead, the library is encouraged to use `module.exports` instead of, or in addition to, `module.exports.default`. So no, the types aren’t wrong, but the package likely isn’t functioning in Node like they intended.
-- **Types incorrectly use a default export.** This happens when a CJS file uses `module.exports =` but its types use `export default`. The correct type declaration for `module.exports = ...` is `export = ...`. This mismatch doesn’t usually present a problem in bundlers, but for Node, TypeScript will falsely think a default import from an ESM file needs an additional `.default`, as in the example from the previous problem.
-
-## Future work
-
-The first things on my roadmap:
-
-- More thorough explanations of problems
-- Support for DefinitelyTyped analysis
-- Official TypeScript module documentation to link to
-
-Some other ideas:
-
-- Use unpkg or something so it uses less data
-- Generate a downloadable reproduction of a problem
-- Analyze traces and failed lookup locations to suggest fixes
+This project attempts to analyze npm package contents for issues with their TypeScript types, particularly ESM-related module resolution issues. Packages can be explored via the [website](https://arethetypeswrong.github.io) or [CLI](./packages/cli). The following kinds of problems can be detected in the `node10`, `node16`, and `bundler` module resolution modes:
+
+* [💀 Resolution failed](./docs/problems/NoResolution.md)
+* [❌ No types](./docs/problems/UntypedResolution.md)
+* [🎭 Masquerading as CJS](./docs/problems/FalseCJS.md)
+* [👺 Masquerading as ESM](./docs/problems/FalseESM.md)
+* [⚠️ ESM (dynamic import only)](./docs/problems/CJSResolvesToESM.md)
+* [🐛 Used fallback condition](./docs/problems/FallbackCondition.md)
+* [🤨 CJS default export](./docs/problems/CJSOnlyExportsDefault.md)
+* [❗️ Incorrect default export](./docs/problems/FalseExportDefault.md)
+* [🚭 Unexpected module syntax](./docs/problems/UnexpectedModuleSyntax.md)
+* [🥴 Internal resolution error](./docs/problems/InternalResolutionError.md)
 
 ## Contributing
 
-- Understanding that the site is rather incomplete, issue reports are ok.
-- I’m open to someone with design chops adding some styles, but I want to keep it simple. Reach out in an issue.
+Contributions are welcome! Take a look at the open issues or read about [how to contribute to open source](https://opensource.guide).

docs/problems/CJSOnlyExportsDefault.md

@@ -0,0 +1,46 @@
+# 🤨 CJS default export
+
+CommonJS module simulates a default export with `exports.default` and `exports.__esModule`, but does not also set `module.exports` for compatibility with Node. Node, and [some bundlers under certain conditions](https://andrewbranch.github.io/interop-test/#synthesizing-default-exports-for-cjs-modules), do not respect the `__esModule` marker, so accessing the intended default export will require a `.default` property access on the default import.
+
+## Explanation
+
+This problem does not indicate that the types are wrong, but rather that the API exposed may have compatibility problems between Node and bundlers, and will need to be consumed in Node ES modules in a way that the author likely did not intend. It occurs when both of the following conditions are true:
+
+* A JavaScript file assigns `exports.default = ...` and has an `exports.__esModule = true` or similar method of setting the `__esModule` flag. (This pattern indicates that the CommonJS module has been transpiled from an ES module that used a default export.)
+* There is not an additional assignment to `module.exports = ...`, indicating that a compatibility pattern like `module.exports.default = module.exports = ...` was not used.
+
+When these are true, imports in Node will behave differently from imports in most bundlers. Node always synthesizes a default export for CommonJS modules that points to their `module.exports` objects, whereas most bundlers use the `__esModule` property as an indicator that the default export of the CommonJS module should be the value found at `exports.default`. So for a CommonJS module like:
+
+```js
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = function f() { /* ... */ };
+```
+
+a program with a default import like:
+
+```js
+import mod from "pkg";
+console.log(mod);
+```
+
+will result in `{ default: [Function: f] }` in Node, but `[Function: f]` in most bundlers. ([This table](https://andrewbranch.github.io/interop-test/#synthesizing-default-exports-for-cjs-modules) shows the behavior of several bundlers and the Bun runtime under different conditions.)
+
+The divergence in behavior between various runtimes and bundlers can be mitigated by assigning the value intended to be the default export to `module.exports`, then additionally assigning a circular `default` property on that object back to itself:
+
+```js
+Object.defineProperty(exports, "__esModule", { value: true });
+function f() { /* ... */ };
+module.exports = f;
+module.exports.default = f;
+```
+
+This compatibility pattern has an odd effect where `f.default.default.default...` out to infinity is equal to `f`, but nonetheless, all runtimes and bundlers will bind a default import of the module to a callable `f`.
+
+## Consequences
+
+* Consumers in Node will need to access the module’s intended export with `mod.default` where `mod` is already a default import, which is likely not the author’s intention.
+* It may be impossible or inconvenient for consumers to write code that works both in Node and in bundlers.
+
+## Common causes
+
+This problem occurs when library authors compile ES modules that use `export default` to CommonJS with a transpiler that does not add the `module.exports` compatibility strategy discussed above (such as `tsc` itself). Library authors who ship CommonJS to npm are encouraged not to use default exports, or to apply a transform to their output that applies such a compatibility layer.

docs/problems/CJSResolvesToESM.md

@@ -0,0 +1,24 @@
+# ⚠️ Entrypoint is ESM-only
+
+A `require` call resolved to an ESM JavaScript file, which is an error in Node and some bundlers. CommonJS consumers will need to use a dynamic import.
+
+## Explanation
+
+This is the “true” version of the [“Masquerading as ESM”](./FalseESM.md) problem. Whereas that problem indicates that the types are ESM even though a CJS implementation is available, this problem indicates that the types and implementation are both ESM even though CJS was requested. The errors the user will see are the same, but in this case, the error is correct about the problem that will occur at runtime. As such, this problem does _not_ indicate that “the types are wrong”; rather, it’s surfaced to highlight that certain consumers will be unable to use this module.
+
+## Consequences
+
+CommonJS consumers in Node will not be able to use this module without a dynamic `import()`, which introduces asynchronicity. Introducing asynchronicity into a large synchronous codebase can be a prohibitively difficult refactor and a breaking change for downstream APIs, so in practice the consequence is often that consumers will not be able to use this module at all.
+
+```ts
+  import mod from "pkg";
+  //              ^^^^^
+  // The current file is a CommonJS module whose imports will produce 'require'
+  // calls; however, the referenced file is an ECMAScript module and cannot be
+  // imported with 'require'. Consider writing a dynamic 'import("pkg")' call
+  // instead.
+  ```
+
+## Common causes
+
+This usually happens when a library only contains ESM after making a conscious decision not to support CommonJS. (This tool tries to be neutral on that decision, but by default shows what happens in many module resolution scenarios. The author of this tool encourages library authors to consider their constraints, understand their users, and move in the direction of ESM-only when possible.)

docs/problems/FallbackCondition.md

@@ -0,0 +1,62 @@
+# 🐛 Used fallback condition
+
+Import resolved to types through a conditional package.json export, but only after failing to resolve through an earlier condition. This behavior is a [TypeScript bug](https://github.com/microsoft/TypeScript/issues/50762). It may misrepresent the runtime behavior of this import and should not be relied upon.
+
+## Explanation
+
+[Node’s algorithm](https://nodejs.org/docs/latest-v20.x/api/esm.html#resolution-algorithm-specification) for resolving package.json `"exports"` requires that resolution stop once a target filename has been tried, whether or not that file could be found. For example, consider resolving an import with conditions `types` and `import` against these `exports`:
+
+```json
+{
+  "exports": {
+    ".": {
+      "types": {
+        "foo": "./didnt-match.d.ts"
+      },
+      "import": {
+        "types": "./doesnt-exist.d.ts",
+        "default": "./exists.mjs"
+      }
+    }
+  }
+}
+```
+
+To simplify the specification, resolution _should_ proceed as follows:
+
+1. Enter the first `"types"` condition because it matches.
+2. Does `"foo"` match? No. Since we haven’t tried to look up a file yet, we can exit `"types"` and continue.
+3. Enter the `"import"` condition because it matches.
+4. Try to look up `"./doesnt-exist.d.ts"` because `"types"` matches.
+5. Fail to find a file at `"./doesnt-exist.d.ts"`, so return a failed resolution result.
+
+TypeScript reimplements this algorithm so it can understand what Node will do and find corresponding types for a given resolution, but TypeScript’s implementation has a known bug. Instead of returning a failed resolution when it can’t find `doesnt-exist.d.ts`, it continues to the next matching condition. In the example above, TypeScript would successfully resolve to `exists.mjs`.
+
+This problem is raised when a resolution occurred only because of this TypeScript bug.
+
+## Consequences
+
+This problem almost always indicates the presence of another (deeper) problem, since a correct resolver implementation would have resulted in a [failed resolution](./NoResolution.md) or an [untyped resolution](./UntypedResolution.md), which themselves are almost always caused by a misconfiguration of the library. Often, the incorrect resolution results in a better experience for the user than a failed resolution would, which makes it difficult for TypeScript to fix the bug. The TypeScript team would want to see occurrences of this issue drop to negligible levels before fixing their resolver algorithm.
+
+## Common causes
+
+This issue commonly occurs in combination with [“Masquerading as CJS”](./FalseCJS.md) or [“Masquerading as ESM”](./FalseESM.md) through a package.json like:
+
+```json
+{
+  "name": "pkg",
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    "import": "./index.mjs",
+    "default": "./index.js"
+  }
+}
+```
+
+where an `index.d.ts` exists but `index.d.mts` does not. TypeScript first does a resolution pass only looking for types and ignoring JavaScript files, so when resolving with the `import` condition, that first pass goes something like:
+
+1. `"import"` matches, so try substituting the `.mjs` extension for the type-equivalent `.d.mts`. `index.d.mts` does not exist, so **continue** (this is the bug).
+2. `"default"` conditions always match, so try substituting the `.js` extension for the type-equivalent `.d.ts`. `index.d.ts` exists, so us that as a resolution result.
+
+But in this example, `index.d.ts` is a CommonJS module since the package.json lacks a `"type": "module"` field, whereas the runtime resolution would have been `index.mjs`, which is an ES module. So, an instance of [“Masquerading as CJS”](./FalseCJS.md) also occurred. If the library adds an `index.d.mts` file to represent the `index.mjs` file, both problems will be solved simultaneously.