doc: clarify module system selection

doc/api/cli.md

@@ -1,4 +1,4 @@
-# Command-line options
+# Command-line API
 
 <!--introduced_in=v5.9.1-->
 
@@ -11,16 +11,42 @@ To view this documentation as a manual page in a terminal, run `man node`.
 
 ## Synopsis
 
-`node [options] [V8 options] [script.js | -e "script" | -] [--] [arguments]`
+`node [options] [V8 options] [<program-entry-point> | -e "script" | -] [--] [arguments]`
 
-`node inspect [script.js | -e "script" | <host>:<port>] …`
+`node inspect [<program-entry-point> | -e "script" | <host>:<port>] …`
 
 `node --v8-options`
 
 Execute without arguments to start the [REPL][].
 
 For more info about `node inspect`, see the [debugger][] documentation.
 
+## Program entry point
+
+The program entry point is a specifier-like string. If the string is not an
+absolute path, it's resolved as a relative path from the current working
+directory. That path is then resolved by [CommonJS][] module loader. If no
+corresponding file is found, an error is thrown.
+
+If a file is found, its path will be passed to the [ECMAScript module loader][]
+under any of the following conditions:
+
+* The file has an `.mjs` extension.
+* The file nearest parent `package.json` file
+  contains a top-level [`"type"`][] field with a value of `"module"`.
+* If the program was started with a command-line flag that forces the entry
+  point to be loaded with ECMAScript module loader.
+
+Otherwise, the file is loaded using the CommonJS module loader. See
+[File modules][] for more details.
+
+### ECMAScript modules loader entry point caveat
+
+When loading [ECMAScript module loader][] loads the program entry point, the `node`
+command will only accept as input only files with `.js`, `.mjs`, or `.cjs`
+extensions; and with `.wasm` extensions when
+[`--experimental-wasm-modules`][] is enabled.
+
 ## Options
 
 <!-- YAML
@@ -277,8 +303,8 @@ Enable experimental JSON support for the ES Module loader.
 added: v9.0.0
 -->
 
-Specify the `module` of a custom experimental [ECMAScript Module loader][].
-`module` may be either a path to a file, or an ECMAScript Module name.
+Specify the `module` of a custom experimental [ECMAScript module loader][].
+`module` may be any string accepted as an [`import` specifier][].
 
 ### `--experimental-policy`
 
@@ -1928,15 +1954,19 @@ $ node --max-old-space-size=1536 index.js
 ```
 
 [Chrome DevTools Protocol]: https://chromedevtools.github.io/devtools-protocol/
-[ECMAScript Module loader]: esm.md#loaders
+[CommonJS]: modules.md
+[ECMAScript module loader]: esm.md#loaders
+[File modules]: modules.md#file-modules
 [OSSL_PROVIDER-legacy]: https://www.openssl.org/docs/man3.0/man7/OSSL_PROVIDER-legacy.html
 [REPL]: repl.md
 [ScriptCoverage]: https://chromedevtools.github.io/devtools-protocol/tot/Profiler#type-ScriptCoverage
 [Source Map]: https://sourcemaps.info/spec.html
 [Subresource Integrity]: https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity
 [V8 JavaScript code coverage]: https://v8project.blogspot.com/2017/12/javascript-code-coverage.html
+[`"type"`]: packages.md#type
 [`--cpu-prof-dir`]: #--cpu-prof-dir
 [`--diagnostic-dir`]: #--diagnostic-dirdirectory
+[`--experimental-wasm-modules`]: #--experimental-wasm-modules
 [`--heap-prof-dir`]: #--heap-prof-dir
 [`--openssl-config`]: #--openssl-configfile
 [`--redirect-warnings`]: #--redirect-warningsfile
@@ -1949,6 +1979,7 @@ $ node --max-old-space-size=1536 index.js
 [`dns.lookup()`]: dns.md#dnslookuphostname-options-callback
 [`dns.setDefaultResultOrder()`]: dns.md#dnssetdefaultresultorderorder
 [`dnsPromises.lookup()`]: dns.md#dnspromiseslookuphostname-options
+[`import` specifier]: esm.md#import-specifiers
 [`process.setUncaughtExceptionCaptureCallback()`]: process.md#processsetuncaughtexceptioncapturecallbackfn
 [`tls.DEFAULT_MAX_VERSION`]: tls.md#tlsdefault_max_version
 [`tls.DEFAULT_MIN_VERSION`]: tls.md#tlsdefault_min_version

doc/api/esm.md

@@ -94,12 +94,12 @@ provides interoperability between them and its original module format,
 
 <!-- type=misc -->
 
-Node.js treats JavaScript code as CommonJS modules by default.
-Authors can tell Node.js to treat JavaScript code as ECMAScript modules
+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, or the
-`--input-type` flag. See
-[Modules: Packages](packages.md#determining-module-system) for more
-details.
+[`--input-type`][] flag. Outside of those cases, Node.js will use the CommonJS
+module loader. See [Determining module system][] for more details.
 
 <!-- Anchors to make sure old links find a target -->
 
@@ -1425,6 +1425,7 @@ success!
 [CommonJS]: modules.md
 [Conditional exports]: packages.md#conditional-exports
 [Core modules]: modules.md#core-modules
+[Determining module system]: packages.md#determining-module-system
 [Dynamic `import()`]: https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import#Dynamic_Imports
 [ECMAScript Top-Level `await` proposal]: https://github.com/tc39/proposal-top-level-await/
 [ES Module Integration Proposal for WebAssembly]: https://github.com/webassembly/esm-integration
@@ -1437,6 +1438,7 @@ success!
 [WHATWG JSON modules specification]: https://html.spec.whatwg.org/#creating-a-json-module-script
 [`"exports"`]: packages.md#exports
 [`"type"`]: packages.md#type
+[`--input-type`]: cli.md#--input-typetype
 [`ArrayBuffer`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer
 [`SharedArrayBuffer`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer
 [`TypedArray`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray

doc/api/modules.md

@@ -61,7 +61,34 @@ module.exports = class Square {
 };
 ```
 
-The module system is implemented in the `require('module')` module.
+The CommonJS module system is implemented in the [`module` core module][].
+
+## Enabling
+
+<!-- type=misc -->
+
+Node.js has two module systems: CommonJS modules and [ECMAScript modules][].
+
+By default, Node.js will treat the following as CommonJS modules:
+
+* Files with a `.cjs` extension;
+
+* 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"`][].
+
+* Files with an extension that is not `.mjs`, `.cjs`, `.json`, `.node`, or `.js`
+  (when the nearest parent `package.json` file contains a top-level field
+  [`"type"`][] with a value of `"module"`, those files will be recognized as
+  CommonJS modules only if they are being `require`d, not when used as the
+  command-line entry point of the program).
+
+See [Determining module system][] for more details.
+
+Calling `require()` always use the CommonJS module loader, calling `import()`
+always use the ECMAScript module loader.
 
 ## Accessing the main module
 
@@ -1047,13 +1074,15 @@ This section was moved to
 [ECMAScript Modules]: esm.md
 [GLOBAL_FOLDERS]: #loading-from-the-global-folders
 [`"main"`]: packages.md#main
+[`"type"`]: packages.md#type
 [`ERR_REQUIRE_ESM`]: errors.md#err_require_esm
 [`Error`]: errors.md#class-error
 [`__dirname`]: #__dirname
 [`__filename`]: #__filename
 [`import()`]: https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import#Dynamic_Imports
 [`module.children`]: #modulechildren
 [`module.id`]: #moduleid
+[`module` core module]: module.md
 [`module` object]: #the-module-object
 [`package.json`]: packages.md#nodejs-packagejson-field-definitions
 [`path.dirname()`]: path.md#pathdirnamepath

doc/api/packages.md

@@ -51,12 +51,13 @@ along with a reference for the [`package.json`][] fields defined by Node.js.
 ## Determining module system
 
 Node.js will treat the following as [ES modules][] when passed to `node` as the
-initial input, or when referenced by `import` statements within ES module code:
+initial input, or when referenced by `import` statements or `import()`
+expressions:
 
-* Files ending in `.mjs`.
+* Files with an `.mjs` extension.
 
-* Files ending in `.js` when the nearest parent `package.json` file contains a
-  top-level [`"type"`][] field with a value of `"module"`.
+* Files with a `.js` extension when the nearest parent `package.json` file
+  contains a top-level [`"type"`][] field with a value of `"module"`.
 
 * Strings passed in as an argument to `--eval`, or piped to `node` via `STDIN`,
   with the flag `--input-type=module`.
@@ -67,12 +68,13 @@ field, or string input without the flag `--input-type`. This behavior is to
 preserve backward compatibility. However, now that Node.js supports both
 CommonJS and ES modules, it is best to be explicit whenever possible. Node.js
 will treat the following as CommonJS when passed to `node` as the initial input,
-or when referenced by `import` statements within ES module code:
+or when referenced by `import` statements, `import()` expressions, or
+`require()` expressions:
 
-* Files ending in `.cjs`.
+* Files with a `.cjs` extension.
 
-* Files ending in `.js` 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
+  contains a top-level field [`"type"`][] with a value of `"commonjs"`.
 
 * Strings passed in as an argument to `--eval` or `--print`, or piped to `node`
   via `STDIN`, with the flag `--input-type=commonjs`.

doc/api/synopsis.md

@@ -88,6 +88,6 @@ Now, open any preferred web browser and visit `http://127.0.0.1:3000`.
 If the browser displays the string `Hello, World!`, that indicates
 the server is working.
 
-[Command-line options]: cli.md#command-line-options
+[Command-line options]: cli.md#options
 [Installing Node.js via package manager]: https://nodejs.org/en/download/package-manager/
 [web server]: http.md

tools/doc/links-mapper.json

@@ -1,6 +1,6 @@
 {
   "doc/api/synopsis.md": {
-    "command line options": "cli.html#command-line-options",
+    "command line options": "cli.html#options",
     "web server": "http.html"
   }
 }