doc: phase 2 documentation

Co-authored-by: Myles Borins <mylesborins@google.com>
Co-authored-by: Evan Plaice <evanplaice@gmail.com>
Co-authored-by: James M Snell <jasnell@gmail.com>

doc/api/cli.md

@@ -134,6 +134,27 @@ added: v6.0.0
 Enable FIPS-compliant crypto at startup. (Requires Node.js to be built with
 `./configure --openssl-fips`.)
 
+### `--es-module-specifier-resolution=mode`
+<!-- YAML
+added: REPLACEME
+-->
+
+To be used in conjunction with `--experimental-modules`. Sets the resolution
+algorithm for resolving specifiers. Valid options are `explicit` and `node`.
+
+The default is `explicit`, which requires providing the full path to a
+module. The `node` mode will enable support for optional file extensions and
+the ability to import a directory that has an index file.
+
+Please see [customizing esm specifier resolution][] for example usage.
+
+### `--experimental-json-modules`
+<!-- YAML
+added: REPLACEME
+-->
+
+Enable experimental JSON support for the ES Module loader.
+
 ### `--experimental-modules`
 <!-- YAML
 added: v8.5.0
@@ -533,17 +554,16 @@ added: v2.4.0
 
 Track heap object allocations for heap snapshots.
 
-### `-m`, `--type=type`
+### `--type=type`
 
-When using `--experimental-modules`, this informs the module resolution type
-to interpret the top-level entry into Node.js.
+Used with `--experimental-modules`, this configures Node.js to interpret the
+initial entry point as CommonJS or as an ES module.
 
-Works with stdin, `--eval`, `--print` as well as standard execution.
+Valid values are `"commonjs"` and `"module"`. The default is to infer from
+the file extension and the `"type"` field in the nearest parent `package.json`.
 
-Valid values are `"commonjs"` and `"module"`, where the default is to infer
-from the file extension and package type boundary.
+Works for executing a file as well as `--eval`, `--print`, `STDIN`.
 
-`-m` is an alias for `--type=module`.
 
 ### `--use-bundled-ca`, `--use-openssl-ca`
 <!-- YAML
@@ -937,9 +957,10 @@ greater than `4` (its current default value). For more information, see the
 [REPL]: repl.html
 [ScriptCoverage]: https://chromedevtools.github.io/devtools-protocol/tot/Profiler#type-ScriptCoverage
 [V8 JavaScript code coverage]: https://v8project.blogspot.com/2017/12/javascript-code-coverage.html
+[customizing esm specifier resolution]: esm.html#esm_customizing_esm_specifier_resolution_algorithm
 [debugger]: debugger.html
 [debugging security implications]: https://nodejs.org/en/docs/guides/debugging-getting-started/#security-implications
 [emit_warning]: process.html#process_process_emitwarning_warning_type_code_ctor
-[experimental ECMAScript Module]: esm.html#esm_experimental_loader_hooks
+[experimental ECMAScript Module]: esm.html#esm_resolve_hook
 [libuv threadpool documentation]: http://docs.libuv.org/en/latest/threadpool.html
 [remote code execution]: https://www.owasp.org/index.php/Code_Injection

doc/api/errors.md

@@ -1445,7 +1445,7 @@ strict compliance with the API specification (which in some cases may accept
 
 > Stability: 1 - Experimental
 
-An [ES6 module][] loader hook specified `format: 'dynamic'` but did not provide
+An [ES Module][] loader hook specified `format: 'dynamic'` but did not provide
 a `dynamicInstantiate` hook.
 
 <a id="ERR_MISSING_MESSAGE_PORT_IN_TRANSFER_LIST"></a>
@@ -1466,7 +1466,7 @@ this error will not occur with standard builds of Node.js.
 
 > Stability: 1 - Experimental
 
-An [ESM module][] could not be resolved.
+An [ES Module][] could not be resolved.
 
 <a id="ERR_MULTIPLE_CALLBACK"></a>
 ### ERR_MULTIPLE_CALLBACK
@@ -1553,7 +1553,7 @@ A given value is out of the accepted range.
 
 > Stability: 1 - Experimental
 
-An attempt was made to `require()` an [ES6 module][].
+An attempt was made to `require()` an [ES Module][].
 
 <a id="ERR_SCRIPT_EXECUTION_INTERRUPTED"></a>
 ### ERR_SCRIPT_EXECUTION_INTERRUPTED
@@ -2219,14 +2219,14 @@ Used in the `repl` in case the old history file is used and an error occurred
 while trying to read and parse it.
 
 <a id="ERR_INVALID_REPL_TYPE"></a>
-### ERR_INVALID_REPL_TYPE
+#### ERR_INVALID_REPL_TYPE
 
 > Stability: 1 - Experimental
 
 The `--type=...` flag is not compatible with the Node.js REPL.
 
 <a id="ERR_TYPE_MISMATCH"></a>
-### ERR_TYPE_MISMATCH
+#### ERR_TYPE_MISMATCH
 
 > Stability: 1 - Experimental
 
@@ -2238,7 +2238,7 @@ a `.js` file where the nearest parent `package.json` either lacks a `"type"`
 field or contains `"type": "commonjs"`.
 
 <a id="ERR_INVALID_TYPE_FLAG"></a>
-### ERR_INVALID_TYPE_FLAG
+#### ERR_INVALID_TYPE_FLAG
 
 > Stability: 1 - Experimental
 
@@ -2247,7 +2247,7 @@ An invalid `--type=...` flag value was provided.
 <a id="ERR_MISSING_DYNAMIC_INSTANTIATE_HOOK"></a>
 #### ERR_MISSING_DYNAMIC_INSTANTIATE_HOOK
 
-Used when an [ES6 module][] loader hook specifies `format: 'dynamic'` but does
+Used when an [ES Module][] loader hook specifies `format: 'dynamic'` but does
 not provide a `dynamicInstantiate` hook.
 
 <a id="ERR_STREAM_HAS_STRINGDECODER"></a>
@@ -2316,7 +2316,7 @@ such as `process.stdout.on('data')`.
 [`subprocess.kill()`]: child_process.html#child_process_subprocess_kill_signal
 [`subprocess.send()`]: child_process.html#child_process_subprocess_send_message_sendhandle_options_callback
 [`zlib`]: zlib.html
-[ES6 module]: esm.html
+[ES Module]: esm.html
 [ICU]: intl.html#intl_internationalization_support
 [Node.js Error Codes]: #nodejs-error-codes
 [V8's stack trace API]: https://github.com/v8/v8/wiki/Stack-Trace-API