cli: add --require-module/--no-require-module

To replace --experimental-require-module and
--no-experimental-require-module. The experimental
ones are left as legacy aliases.

PR-URL: #60959
Reviewed-By: Jacob Smith <jacob@frende.me>
Reviewed-By: Marco Ippolito <marcoippolito54@gmail.com>
Reviewed-By: Jordan Harband <ljharb@gmail.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>

Author: joyeecheung

doc/api/cli.md

@@ -1137,27 +1137,6 @@ If the ES module being `require()`'d contains top-level `await`, this flag
 allows Node.js to evaluate the module, try to locate the
 top-level awaits, and print their location to help users find them.
 
-### `--experimental-require-module`
-
-<!-- YAML
-added:
-  - v22.0.0
-  - v20.17.0
-changes:
-  - version:
-    - v23.0.0
-    - v22.12.0
-    - v20.19.0
-    pr-url: https://github.com/nodejs/node/pull/55085
-    description: This is now true by default.
--->
-
-> Stability: 1.1 - Active Development
-
-Supports loading a synchronous ES module graph in `require()`.
-
-See [Loading ECMAScript modules using `require()`][].
-
 ### `--experimental-sea-config`
 
 <!-- YAML
@@ -1845,6 +1824,11 @@ added:
   - v22.0.0
   - v20.17.0
 changes:
+  - version:
+    - REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/60959
+    description: The flag was renamed from `--no-experimental-require-module` to
+                 `--no-require-module`, with the former marked as legacy.
   - version:
     - v23.0.0
     - v22.12.0
@@ -1853,11 +1837,9 @@ changes:
     description: This is now false by default.
 -->
 
-> Stability: 1.1 - Active Development
-
-Disable support for loading a synchronous ES module graph in `require()`.
+> Stability: 3 - Legacy: Use [`--no-require-module`][] instead.
 
-See [Loading ECMAScript modules using `require()`][].
+Legacy alias for [`--no-require-module`][].
 
 ### `--no-experimental-sqlite`
 
@@ -1922,6 +1904,34 @@ changes:
 Disables the family autoselection algorithm unless connection options explicitly
 enables it.
 
+<a id="--experimental-require-module"></a>
+
+### `--no-require-module`
+
+<!-- YAML
+added:
+  - v22.0.0
+  - v20.17.0
+changes:
+  - version:
+    - REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/60959
+    description: This flag was renamed from `--no-experimental-require-module`
+                 to `--no-require-module`.
+  - version:
+    - v23.0.0
+    - v22.12.0
+    - v20.19.0
+    pr-url: https://github.com/nodejs/node/pull/55085
+    description: This is now false by default.
+-->
+
+> Stability: 1.2 - Release Candidate
+
+Disable support for loading a synchronous ES module graph in `require()`.
+
+See [Loading ECMAScript modules using `require()`][].
+
 ### `--no-strip-types`
 
 <!-- YAML
@@ -3531,6 +3541,7 @@ one is included in the list below.
 * `--report-on-signal`
 * `--report-signal`
 * `--report-uncaught-exception`
+* `--require-module`
 * `--require`, `-r`
 * `--secure-heap-min`
 * `--secure-heap`
@@ -4067,6 +4078,7 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12
 [`--experimental-webstorage`]: #--experimental-webstorage
 [`--heap-prof-dir`]: #--heap-prof-dir
 [`--import`]: #--importmodule
+[`--no-require-module`]: #--no-require-module
 [`--no-strip-types`]: #--no-strip-types
 [`--openssl-config`]: #--openssl-configfile
 [`--preserve-symlinks`]: #--preserve-symlinks

doc/api/modules.md

@@ -324,8 +324,8 @@ If `--experimental-print-required-tla` is enabled, instead of throwing
 module, try to locate the top-level awaits, and print their location to
 help users fix them.
 
-Support for loading ES modules using `require()` is currently
-experimental and can be disabled using `--no-experimental-require-module`.
+If support for loading ES modules using `require()` results in unexpected
+breakage, it can be disabled using `--no-require-module`.
 To print where this feature is used, use [`--trace-require-module`][].
 
 This feature can be detected by checking if
@@ -422,7 +422,7 @@ LOAD_PACKAGE_IMPORTS(X, DIR)
 1. Find the closest package scope SCOPE to DIR.
 2. If no scope was found, return.
 3. If the SCOPE/package.json "imports" is null or undefined, return.
-4. If `--experimental-require-module` is enabled
+4. If `--no-require-module` is not enabled
   a. let CONDITIONS = ["node", "require", "module-sync"]
   b. Else, let CONDITIONS = ["node", "require"]
 5. let MATCH = PACKAGE_IMPORTS_RESOLVE(X, pathToFileURL(SCOPE),
@@ -436,7 +436,7 @@ LOAD_PACKAGE_EXPORTS(X, DIR)
    return.
 3. Parse DIR/NAME/package.json, and look for "exports" field.
 4. If "exports" is null or undefined, return.
-5. If `--experimental-require-module` is enabled
+5. If `--no-require-module` is not enabled
   a. let CONDITIONS = ["node", "require", "module-sync"]
   b. Else, let CONDITIONS = ["node", "require"]
 6. let MATCH = PACKAGE_EXPORTS_RESOLVE(pathToFileURL(DIR/NAME), "." + SUBPATH,

doc/node-config-schema.json

@@ -343,6 +343,9 @@
             }
           ]
         },
+        "require-module": {
+          "type": "boolean"
+        },
         "secure-heap": {
           "type": "number"
         },

doc/node.1

@@ -213,6 +213,9 @@ Disable top-level await keyword support in REPL.
 .It Fl -no-experimental-sqlite
 Disable the experimental node:sqlite module.
 .
+.It Fl -no-require-module
+Disable support for loading ECMAScript modules with require().
+.
 .It Fl -no-strip-types
 Disable type-stripping for TypeScript files.
 .

lib/internal/bootstrap/node.js

@@ -283,7 +283,7 @@ const features = {
     return binding.hasCachedBuiltins();
   },
   get require_module() {
-    return getOptionValue('--experimental-require-module');
+    return getOptionValue('--require-module');
   },
 };
 

lib/internal/modules/cjs/loader.js

@@ -1737,7 +1737,7 @@ function wrapSafe(filename, content, cjsModuleInstance, format) {
     } else {
       // For modules being loaded by `require()`, if require(esm) is disabled,
       // don't try to reparse to detect format and just throw for ESM syntax.
-      shouldDetectModule = getOptionValue('--experimental-require-module');
+      shouldDetectModule = getOptionValue('--require-module');
     }
   }
   const result = compileFunctionForCJSLoader(content, filename, false /* is_sea_main */, shouldDetectModule);
@@ -1936,7 +1936,7 @@ Module._extensions['.js'] = function(module, filename) {
   const { source, format: loadedFormat } = loadSource(module, filename, format);
   // Function require shouldn't be used in ES modules when require(esm) is disabled.
   if ((loadedFormat === 'module' || loadedFormat === 'module-typescript') &&
-    !getOptionValue('--experimental-require-module')) {
+    !getOptionValue('--require-module')) {
     const err = getRequireESMError(module, pkg, source, filename);
     throw err;
   }

lib/internal/modules/esm/loader.js

@@ -305,7 +305,7 @@ class ModuleLoader {
    */
   importSyncForRequire(mod, filename, source, isMain, parent) {
     const url = pathToFileURL(filename).href;
-    if (!getOptionValue('--experimental-require-module')) {
+    if (!getOptionValue('--require-module')) {
       throw new ERR_REQUIRE_ESM(url, true);
     }
 
@@ -495,7 +495,7 @@ class ModuleLoader {
     }
 
     if (formatFromLoad === 'module' || formatFromLoad === 'module-typescript') {
-      if (!getOptionValue('--experimental-require-module')) {
+      if (!getOptionValue('--require-module')) {
         throw new ERR_REQUIRE_ESM(url, true);
       }
     }

lib/internal/modules/esm/utils.js

@@ -75,7 +75,7 @@ function initializeDefaultConditions() {
   const userConditions = getOptionValue('--conditions');
   const noAddons = getOptionValue('--no-addons');
   const addonConditions = noAddons ? [] : ['node-addons'];
-  const moduleConditions = getOptionValue('--experimental-require-module') ? ['module-sync'] : [];
+  const moduleConditions = getOptionValue('--require-module') ? ['module-sync'] : [];
   defaultConditions = ObjectFreeze([
     'node',
     'import',

lib/internal/modules/helpers.js

@@ -84,7 +84,7 @@ function initializeCjsConditions() {
     ...addonConditions,
     ...userConditions,
   ];
-  if (getOptionValue('--experimental-require-module')) {
+  if (getOptionValue('--require-module')) {
     cjsConditionsArray.push('module-sync');
   }
   ObjectFreeze(cjsConditionsArray);

src/node_options.cc

@@ -486,17 +486,23 @@ EnvironmentOptionsParser::EnvironmentOptionsParser() {
             kAllowedInEnvvar,
             true);
   AddOption("--experimental-print-required-tla",
-            "Print pending top-level await. If --experimental-require-module "
+            "Print pending top-level await. If --require-module "
             "is true, evaluate asynchronous graphs loaded by `require()` but "
             "do not run the microtasks, in order to to find and print "
             "top-level await in the graph",
             &EnvironmentOptions::print_required_tla,
             kAllowedInEnvvar);
-  AddOption("--experimental-require-module",
+  AddOption("--require-module",
             "Allow loading synchronous ES Modules in require().",
             &EnvironmentOptions::require_module,
             kAllowedInEnvvar,
             true);
+  AddOption("--experimental-require-module",
+            "Legacy alias for --require-module",
+            &EnvironmentOptions::require_module,
+            kAllowedInEnvvar,
+            true);
+  Implies("--experimental-require-module", "--require-module");
   AddOption("--diagnostic-dir",
             "set dir for all output files"
             " (default: current working directory)",