Fixes #31219
Fixes #29038

Reincarnation of #32150

The Problem

For a given combination of script kind (JS or TS), module target, module interop settings (esModuleInterop and allowSyntheticDefaultImports), and exported symbol that you want to import, there are anywhere between zero and two correct-ish ways to write an import for that exported symbol. Prior to this PR,

export = x;

was always auto-imported as

import x = require("./x");

This is never valid when either of the following are true:

• The module target is es2015 or higher
• The importing file is JavaScript

It’s also potentially undesirable, while not wrong, when all of the following are true:

• The module target is CommonJS/AMD/UMD
• The importing file is TypeScript
• esModuleInterop or allowSyntheticDefaultImports is true

In this scenario, both import x = require("./x") and import x from "./x" are valid, and it’s debatable which one should be preferred.

The Solution

The No-Brainer Part: Use the Default Import When It’s The Only Valid Choice

When the module target is es2015+ and esModuleInterop or allowSyntheticDefaultImports is enabled and the importing file is TypeScript, the default import is the only thing that works for export =. (When the importing file is JavaScript, the intent is also very likely to have a default import, even though const x = require('./x') is an option, so this logic applies to JS too.)

The JavaScript Part: Use Simple Usage Heuristics

Relying heavily on compiler options to make decisions about what to do in a JavaScript file isn’t a great idea, because many users won’t have a tsconfig/jsconfig at all, and will just be going with the defaults. It’s highly likely that, if there are any signs of the ES module system in the file, they’re working with a bundler that does have ES module support, and we should essentially pretend esModuleInterop is turned on and give them the default import.

If it doesn’t look like the importing JS file is an ES module, we’ll give them const x = require("./x"), which we didn’t support at all before this PR.

Additionally, UMD imports are affected here, as JavaScript without esModuleInterop/allowSyntheticDefaultImports/es2015+ module target was getting the TypeScript-specific import x = require("./x"). Now, if the file looks like an ES module and it’s JavaScript, it gets a namespace import (import * as x from "./x"), and if it doesn’t look like a module it gets const x = require("./x") (although currently, I don’t believe that path ever gets taken since a non-module will be happy with using the UMD export as a global).

The Other Part: Use More Sophisticated Heuristics

When the importing file is TypeScript and esModuleInterop or allowSyntheticDefaultImports is enabled and the module target is CommonJS or AMD or UMD, both import x = require('./x') and import x from './x' will work. The former is arguably more correct, but the latter is arguably preferable given the compiler options. After listening to differing opinions amongst the team, I decided to ignore all of them, including my own, and listen to the user’s opinion instead. We search for an existing default import that’s being used to import an export =, and if we find one, we give them import x from './x'. If we don‘t find one, we default to import x = require('./x').

The Part I Didn’t Do: JavaScript require For ES Modules

On one hand, if we’re adding support for inserting const x = require('./x') for a CommonJS export in JavaScript when we think you may not be able to use import, you could argue that we should follow suit and also offer const { y } = require('./x') and const z = require('./z').default for named and default ESM exports, respectively. On the other hand, you could also argue that those are not a valid way to import ES modules, so we’re offering you the only thing that’s technically correct. On the other other hand, you could argue that in today’s ecosystem, modules that TypeScript thinks are ES modules are almost certainly actually CommonJS with interop stuff baked in, so require would work and we should offer it in the name of pragmatism.

I wasn’t sure what to do with this, so I left it as-is, which means in a JavaScript file you could end up taking an auto-import that gives you const x = require('./x') followed by one that gives you import { y } from './y' which is a little odd.