esm: detect ESM syntax in ambiguous JavaScript

Author: GeoffreyBooth

doc/api/esm.md

@@ -109,11 +109,21 @@ provides interoperability between them and its original module format,
 
 Node.js has two module systems: [CommonJS][] modules and ECMAScript modules.
 
-Authors can tell Node.js to use the ECMAScript modules loader via the `.mjs`
-file extension, the `package.json` [`"type"`][] field, the [`--input-type`][]
-flag, or the [`--experimental-default-type`][] flag. Outside of those cases,
-Node.js will use the CommonJS module loader. See [Determining module system][]
-for more details.
+Authors can tell Node.js to interpret JavaScript as an ES module via the `.mjs`
+file extension, the `package.json` [`"type"`][] field with a value `"module"`,
+the [`--input-type`][] flag with a value of `"module"`, or the
+[`--experimental-default-type`][] flag with a value of `"module"`. These are
+explicit markers of code being intended to run as an ES module.
+
+Inversely, authors can tell Node.js to interpret JavaScript as CommonJS via the
+`.cjs` file extension, the `package.json` [`"type"`][] field with a value
+`"commonjs"`, the [`--input-type`][] flag with a value of `"commonjs"`, or the
+[`--experimental-default-type`][] flag with a value of `"commonjs"`.
+
+When code lacks explicit markers for either module system, Node.js will attempt
+to run JavaScript as CommonJS; if it errors due to syntax that is only supported
+in ES modules, it will try again to run the code as an ES module. See
+[Determining module system][] for more details.
 
 <!-- Anchors to make sure old links find a target -->
 
@@ -1019,18 +1029,33 @@ _isImports_, _conditions_)
 >    1. Return _"commonjs"_.
 > 4. If _url_ ends in _".json"_, then
 >    1. Return _"json"_.
-> 5. Let _packageURL_ be the result of **LOOKUP\_PACKAGE\_SCOPE**(_url_).
-> 6. Let _pjson_ be the result of **READ\_PACKAGE\_JSON**(_packageURL_).
-> 7. If _pjson?.type_ exists and is _"module"_, then
->    1. If _url_ ends in _".js"_ or has no file extension, then
->       1. If `--experimental-wasm-modules` is enabled and the file at _url_
->          contains the header for a WebAssembly module, then
->          1. Return _"wasm"_.
->       2. Otherwise,
->          1. Return _"module"_.
->    2. Return **undefined**.
-> 8. Otherwise,
->    1. Return **undefined**.
+> 5. If `--experimental-wasm-modules` is enabled and _url_ ends in
+>    _".wasm"_, then
+>    1. Return _"wasm"_.
+> 6. Let _packageURL_ be the result of **LOOKUP\_PACKAGE\_SCOPE**(_url_).
+> 7. Let _pjson_ be the result of **READ\_PACKAGE\_JSON**(_packageURL_).
+> 8. Let _packageType_ be **null**.
+> 9. If _pjson?.type_ is _"module"_ or _"commonjs"_, then
+>    1. Set _packageType_ to _pjson.type_.
+> 10. If _url_ ends in _".js"_, then
+>    1. If _packageType_ is not **null**, then
+>       1. Return _packageType_.
+>    2. If `--experimental-detect-module` is enabled and the source of
+>       module contains static import or export syntax, then
+>       1. Return _"module"_.
+>    3. Return _"commonjs"_.
+> 11. If _url_ does not have any extension, then
+>    1. If _packageType_ is _"module"_ and `--experimental-wasm-modules` is
+>       enabled and the file at _url_ contains the header for a WebAssembly
+>       module, then
+>       1. Return _"wasm"_.
+>    2. If _packageType_ is not **null**, then
+>       1. Return _packageType_.
+>    3. If `--experimental-detect-module` is enabled and the source of
+>       module contains static import or export syntax, then
+>       1. Return _"module"_.
+>    4. Return _"commonjs"_.
+> 12. Return **undefined** (will throw during load phase).
 
 **LOOKUP\_PACKAGE\_SCOPE**(_url_)
 

doc/api/modules.md

@@ -80,8 +80,10 @@ By default, Node.js will treat the following as CommonJS modules:
 * Files with a `.js` extension when the nearest parent `package.json` file
   contains a top-level field [`"type"`][] with a value of `"commonjs"`.
 
-* Files with a `.js` extension when the nearest parent `package.json` file
-  doesn't contain a top-level field [`"type"`][]. Package authors should include
+* Files with a `.js` extension or without an extension, when the nearest parent
+  `package.json` file doesn't contain a top-level field [`"type"`][] or there is
+  no `package.json` in any parent folder; unless the file contains syntax that
+  errors unless it is evaluated as an ES module. Package authors should include
   the [`"type"`][] field, even in packages where all sources are CommonJS. Being
   explicit about the `type` of the package will make things easier for build
   tools and loaders to determine how the files in the package should be

doc/api/packages.md

@@ -69,6 +69,14 @@ expressions:
 * Strings passed in as an argument to `--eval`, or piped to `node` via `STDIN`,
   with the flag `--input-type=module`.
 
+* Code that contains syntax that only parses successfully as [ES modules][],
+  such as `import` or `export` statements or `import.meta`, when the code has no
+  explicit marker of how it should be interpreted. Explicit markers are `.mjs`
+  or `.cjs` extensions, `package.json` `"type"` fields with either `"module"` or
+  `"commonjs"` values, or `--input-type` or `--experimental-default-type` flags.
+  Dynamic `import()` expressions are supported in either CommonJS or ES modules
+  and would not cause a file to be treated as an ES module.
+
 Node.js will treat the following as [CommonJS][] when passed to `node` as the
 initial input, or when referenced by `import` statements or `import()`
 expressions: