src: rename --loader to --experimental-loader

Renames the `--loader` cli argument to `--experimental-loader`.  This is
to clearly indicate the esm loader feature as experimental even after
esm is no longer experimental.

Also minorly alters the `--experimental-loader` docs to say that the
passed loader can be an esm module.

Refs: nodejs/modules#351 (comment)

PR-URL: #29752
Reviewed-By: Guy Bedford <guybedford@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: David Carlier <devnexen@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>

Author: reasonablytall

doc/api/cli.md

@@ -395,12 +395,13 @@ Specify ways of the inspector web socket url exposure.
 By default inspector websocket url is available in stderr and under `/json/list`
 endpoint on `http://host:port/json/list`.
 
-### `--loader=file`
+### `--experimental-loader=module`
 <!-- YAML
 added: v9.0.0
 -->
 
-Specify the `file` of the custom [experimental ECMAScript Module][] loader.
+Specify the `module` of a custom [experimental ECMAScript Module][] loader.
+`module` may be either a path to a file, or an ECMAScript Module name.
 
 ### `--max-http-header-size=size`
 <!-- YAML
@@ -1001,6 +1002,7 @@ Node.js options that are allowed are:
 * `--enable-fips`
 * `--es-module-specifier-resolution`
 * `--experimental-exports`
+* `--experimental-loader`
 * `--experimental-modules`
 * `--experimental-policy`
 * `--experimental-repl-await`
@@ -1018,7 +1020,6 @@ Node.js options that are allowed are:
 * `--inspect-port`, `--debug-port`
 * `--inspect-publish-uid`
 * `--inspect`
-* `--loader`
 * `--max-http-header-size`
 * `--napi-modules`
 * `--no-deprecation`

doc/api/esm.md

@@ -632,7 +632,7 @@ would provide the exports interface for the instantiation of `module.wasm`.
 <!-- type=misc -->
 
 To customize the default module resolution, loader hooks can optionally be
-provided via a `--loader ./loader-name.mjs` argument to Node.js.
+provided via a `--experimental-loader ./loader-name.mjs` argument to Node.js.
 
 When hooks are used they only apply to ES module loading and not to any
 CommonJS modules loaded.
@@ -731,7 +731,7 @@ export async function resolve(specifier,
 With this loader, running:
 
 ```console
-NODE_OPTIONS='--experimental-modules --loader ./custom-loader.mjs' node x.js
+NODE_OPTIONS='--experimental-modules --experimental-loader ./custom-loader.mjs' node x.js
 ```
 
 would load the module `x.js` as an ES module with relative resolution support

doc/node.1

@@ -200,9 +200,9 @@ Default is
 V8 Inspector integration allows attaching Chrome DevTools and IDEs to Node.js instances for debugging and profiling.
 It uses the Chrome DevTools Protocol.
 .
-.It Fl -loader Ns = Ns Ar file
+.It Fl -experimental-loader Ns = Ns Ar module
 Specify the
-.Ar file
+.Ar module
 as a custom loader, to load
 .Fl -experimental-modules .
 .

lib/internal/bootstrap/pre_execution.js

@@ -400,12 +400,12 @@ function initializeESMLoader() {
     // track of for different ESM modules.
     setInitializeImportMetaObjectCallback(esm.initializeImportMetaObject);
     setImportModuleDynamicallyCallback(esm.importModuleDynamicallyCallback);
-    const userLoader = getOptionValue('--loader');
-    // If --loader is specified, create a loader with user hooks. Otherwise
-    // create the default loader.
+    const userLoader = getOptionValue('--experimental-loader');
+    // If --experimental-loader is specified, create a loader with user hooks.
+    // Otherwise create the default loader.
     if (userLoader) {
       const { emitExperimentalWarning } = require('internal/util');
-      emitExperimentalWarning('--loader');
+      emitExperimentalWarning('--experimental-loader');
     }
     esm.initializeLoader(process.cwd(), userLoader);
   }

src/node_options.cc

@@ -114,7 +114,8 @@ void PerIsolateOptions::CheckOptions(std::vector<std::string>* errors) {
 
 void EnvironmentOptions::CheckOptions(std::vector<std::string>* errors) {
   if (!userland_loader.empty() && !experimental_modules) {
-    errors->push_back("--loader requires --experimental-modules be enabled");
+    errors->push_back("--experimental-loader requires "
+                      "--experimental-modules be enabled");
   }
   if (has_policy_integrity_string && experimental_policy.empty()) {
     errors->push_back("--policy-integrity requires "
@@ -315,6 +316,12 @@ EnvironmentOptionsParser::EnvironmentOptionsParser() {
             "experimental support for exports in package.json",
             &EnvironmentOptions::experimental_exports,
             kAllowedInEnvironment);
+  AddOption("--experimental-loader",
+            "(with --experimental-modules) use the specified file as a "
+            "custom loader",
+            &EnvironmentOptions::userland_loader,
+            kAllowedInEnvironment);
+  AddAlias("--loader", "--experimental-loader");
   AddOption("--experimental-modules",
             "experimental ES Module support and caching modules",
             &EnvironmentOptions::experimental_modules,
@@ -376,11 +383,6 @@ EnvironmentOptionsParser::EnvironmentOptionsParser() {
             "set module type for string input",
             &EnvironmentOptions::module_type,
             kAllowedInEnvironment);
-  AddOption("--loader",
-            "(with --experimental-modules) use the specified file as a "
-            "custom loader",
-            &EnvironmentOptions::userland_loader,
-            kAllowedInEnvironment);
   AddOption("--es-module-specifier-resolution",
             "Select extension resolution algorithm for es modules; "
             "either 'explicit' (default) or 'node'",

test/es-module/test-esm-example-loader.js

@@ -1,4 +1,4 @@
-// Flags: --experimental-modules --loader ./test/fixtures/es-module-loaders/example-loader.mjs
+// Flags: --experimental-modules --experimental-loader ./test/fixtures/es-module-loaders/example-loader.mjs
 /* eslint-disable node-core/require-common-first, node-core/required-modules */
 import assert from 'assert';
 import ok from '../fixtures/es-modules/test-esm-ok.mjs';

test/es-module/test-esm-loader-dependency.mjs

@@ -1,4 +1,4 @@
-// Flags: --experimental-modules --loader ./test/fixtures/es-module-loaders/loader-with-dep.mjs
+// Flags: --experimental-modules --experimental-loader ./test/fixtures/es-module-loaders/loader-with-dep.mjs
 /* eslint-disable node-core/require-common-first, node-core/required-modules */
 import '../fixtures/es-modules/test-esm-ok.mjs';
 

test/es-module/test-esm-loader-invalid-format.mjs

@@ -1,4 +1,4 @@
-// Flags: --experimental-modules --loader ./test/fixtures/es-module-loaders/loader-invalid-format.mjs
+// Flags: --experimental-modules --experimental-loader ./test/fixtures/es-module-loaders/loader-invalid-format.mjs
 import { expectsError, mustCall } from '../common/index.mjs';
 import assert from 'assert';
 

test/es-module/test-esm-loader-invalid-url.mjs

@@ -1,4 +1,4 @@
-// Flags: --experimental-modules --loader ./test/fixtures/es-module-loaders/loader-invalid-url.mjs
+// Flags: --experimental-modules --experimental-loader ./test/fixtures/es-module-loaders/loader-invalid-url.mjs
 import { expectsError, mustCall } from '../common/index.mjs';
 import assert from 'assert';
 

test/es-module/test-esm-loader-missing-dynamic-instantiate-hook.mjs

@@ -1,4 +1,4 @@
-// Flags: --experimental-modules --loader ./test/fixtures/es-module-loaders/missing-dynamic-instantiate-hook.mjs
+// Flags: --experimental-modules --experimental-loader ./test/fixtures/es-module-loaders/missing-dynamic-instantiate-hook.mjs
 import { expectsError } from '../common/index.mjs';
 
 import('test').catch(expectsError({

test/es-module/test-esm-named-exports.mjs

@@ -1,4 +1,4 @@
-// Flags: --experimental-modules --loader ./test/fixtures/es-module-loaders/builtin-named-exports-loader.mjs
+// Flags: --experimental-modules --experimental-loader ./test/fixtures/es-module-loaders/builtin-named-exports-loader.mjs
 import '../common/index.mjs';
 import { readFile } from 'fs';
 import assert from 'assert';

test/es-module/test-esm-preserve-symlinks-not-found-plain.mjs

@@ -1,3 +1,3 @@
-// Flags: --experimental-modules --loader ./test/fixtures/es-module-loaders/not-found-assert-loader.mjs
+// Flags: --experimental-modules --experimental-loader ./test/fixtures/es-module-loaders/not-found-assert-loader.mjs
 /* eslint-disable node-core/require-common-first, node-core/required-modules */
 import './not-found.js';

test/es-module/test-esm-preserve-symlinks-not-found.mjs

@@ -1,3 +1,3 @@
-// Flags: --experimental-modules --loader ./test/fixtures/es-module-loaders/not-found-assert-loader.mjs
+// Flags: --experimental-modules --experimental-loader ./test/fixtures/es-module-loaders/not-found-assert-loader.mjs
 /* eslint-disable node-core/require-common-first, node-core/required-modules */
 import './not-found.mjs';

test/es-module/test-esm-resolve-hook.mjs

@@ -1,4 +1,4 @@
-// Flags: --experimental-modules --loader ./test/fixtures/es-module-loaders/js-loader.mjs
+// Flags: --experimental-modules --experimental-loader ./test/fixtures/es-module-loaders/js-loader.mjs
 /* eslint-disable node-core/require-common-first, node-core/required-modules */
 import { namedExport } from '../fixtures/es-module-loaders/js-as-esm.js';
 import assert from 'assert';

test/es-module/test-esm-shared-loader-dep.mjs

@@ -1,4 +1,4 @@
-// Flags: --experimental-modules --loader ./test/fixtures/es-module-loaders/loader-shared-dep.mjs
+// Flags: --experimental-modules --experimental-loader ./test/fixtures/es-module-loaders/loader-shared-dep.mjs
 import { createRequire } from '../common/index.mjs';
 
 import assert from 'assert';

test/parallel/test-loaders-unknown-builtin-module.mjs

@@ -1,4 +1,4 @@
-// Flags: --experimental-modules --loader ./test/fixtures/es-module-loaders/loader-unknown-builtin-module.mjs
+// Flags: --experimental-modules --experimental-loader ./test/fixtures/es-module-loaders/loader-unknown-builtin-module.mjs
 import { expectsError, mustCall } from '../common/index.mjs';
 import assert from 'assert';
 

test/parallel/test-process-env-allowed-flags-are-documented.js

@@ -87,6 +87,7 @@ const undocumented = difference(process.allowedNodeEnvironmentFlags,
 assert(undocumented.delete('--debug-arraybuffer-allocations'));
 assert(undocumented.delete('--experimental-worker'));
 assert(undocumented.delete('--no-node-snapshot'));
+assert(undocumented.delete('--loader'));
 
 assert.strictEqual(undocumented.size, 0,
                    'The following options are not documented as allowed in ' +