module: print location of unsettled top-level await in entry points

.github/CODEOWNERS

@@ -96,7 +96,6 @@
 /doc/api/packages.md @nodejs/loaders
 /lib/internal/bootstrap/realm.js @nodejs/loaders
 /lib/internal/modules/* @nodejs/loaders
-/lib/internal/process/esm_loader.js @nodejs/loaders
 /lib/internal/process/execution.js @nodejs/loaders
 /lib/module.js @nodejs/loaders
 /src/module_wrap* @nodejs/loaders @nodejs/vm

doc/api/process.md

@@ -3953,8 +3953,8 @@ cases:
   and generally can only happen during development of Node.js itself.
 * `12` **Invalid Debug Argument**: The `--inspect` and/or `--inspect-brk`
   options were set, but the port number chosen was invalid or unavailable.
-* `13` **Unfinished Top-Level Await**: `await` was used outside of a function
-  in the top-level code, but the passed `Promise` never resolved.
+* `13` **Unsettled Top-Level Await**: `await` was used outside of a function
+  in the top-level code, but the passed `Promise` never settled.
 * `14` **Snapshot Failure**: Node.js was started to build a V8 startup
   snapshot and it failed because certain requirements of the state of
   the application were not met.

lib/internal/main/check_syntax.js

@@ -50,8 +50,7 @@ function loadESMIfNeeded(cb) {
   const hasModulePreImport = getOptionValue('--import').length > 0;
 
   if (hasModulePreImport) {
-    const { loadESM } = require('internal/process/esm_loader');
-    loadESM(cb);
+    require('internal/modules/run_main').runEntryPointWithESMLoader(cb);
     return;
   }
   cb();
@@ -76,7 +75,5 @@ async function checkSyntax(source, filename) {
     return;
   }
 
-  const { loadESM } = require('internal/process/esm_loader');
-  const { handleMainPromise } = require('internal/modules/run_main');
-  handleMainPromise(loadESM((loader) => wrapSafe(filename, source)));
+  wrapSafe(filename, source);
 }

lib/internal/main/eval_stdin.js

@@ -10,7 +10,7 @@ const {
 const { getOptionValue } = require('internal/options');
 
 const {
-  evalModule,
+  evalModuleEntryPoint,
   evalScript,
   readStdin,
 } = require('internal/process/execution');
@@ -24,15 +24,15 @@ readStdin((code) => {
   process._eval = code;
 
   const print = getOptionValue('--print');
-  const loadESM = getOptionValue('--import').length > 0;
+  const shouldLoadESM = getOptionValue('--import').length > 0;
   if (getOptionValue('--input-type') === 'module' ||
     (getOptionValue('--experimental-default-type') === 'module' && getOptionValue('--input-type') !== 'commonjs')) {
-    evalModule(code, print);
+    evalModuleEntryPoint(code, print);
   } else {
     evalScript('[stdin]',
                code,
                getOptionValue('--inspect-brk'),
                print,
-               loadESM);
+               shouldLoadESM);
   }
 });

lib/internal/main/eval_string.js

@@ -13,7 +13,7 @@ const {
   prepareMainThreadExecution,
   markBootstrapComplete,
 } = require('internal/process/pre_execution');
-const { evalModule, evalScript } = require('internal/process/execution');
+const { evalModuleEntryPoint, evalScript } = require('internal/process/execution');
 const { addBuiltinLibsToObject } = require('internal/modules/helpers');
 
 const { getOptionValue } = require('internal/options');
@@ -24,10 +24,10 @@ markBootstrapComplete();
 
 const source = getOptionValue('--eval');
 const print = getOptionValue('--print');
-const loadESM = getOptionValue('--import').length > 0 || getOptionValue('--experimental-loader').length > 0;
+const shouldLoadESM = getOptionValue('--import').length > 0 || getOptionValue('--experimental-loader').length > 0;
 if (getOptionValue('--input-type') === 'module' ||
   (getOptionValue('--experimental-default-type') === 'module' && getOptionValue('--input-type') !== 'commonjs')) {
-  evalModule(source, print);
+  evalModuleEntryPoint(source, print);
 } else {
   // For backward compatibility, we want the identifier crypto to be the
   // `node:crypto` module rather than WebCrypto.
@@ -54,5 +54,5 @@ if (getOptionValue('--input-type') === 'module' ||
              ) : source,
              getOptionValue('--inspect-brk'),
              print,
-             loadESM);
+             shouldLoadESM);
 }

lib/internal/main/repl.js

@@ -35,8 +35,7 @@ if (process.env.NODE_REPL_EXTERNAL_MODULE) {
     process.exit(kInvalidCommandLineArgument);
   }
 
-  const esmLoader = require('internal/process/esm_loader');
-  esmLoader.loadESM(() => {
+  require('internal/modules/run_main').runEntryPointWithESMLoader(() => {
     console.log(`Welcome to Node.js ${process.version}.\n` +
       'Type ".help" for more information.');
 
@@ -64,5 +63,7 @@ if (process.env.NODE_REPL_EXTERNAL_MODULE) {
                  getOptionValue('--inspect-brk'),
                  getOptionValue('--print'));
     }
+    // The TLAs in the REPL are still run as scripts, just transformed as async
+    // IIFEs for the REPL code itself to await on.
   });
 }

lib/internal/main/worker_thread.js

@@ -170,8 +170,8 @@ port.on('message', (message) => {
       }
 
       case 'module': {
-        const { evalModule } = require('internal/process/execution');
-        PromisePrototypeThen(evalModule(filename), undefined, (e) => {
+        const { evalModuleEntryPoint } = require('internal/process/execution');
+        PromisePrototypeThen(evalModuleEntryPoint(filename), undefined, (e) => {
           workerOnGlobalUncaughtException(e, true);
         });
         break;

lib/internal/modules/esm/hooks.js

@@ -32,7 +32,7 @@ const {
   ERR_METHOD_NOT_IMPLEMENTED,
   ERR_WORKER_UNSERIALIZABLE_ERROR,
 } = require('internal/errors').codes;
-const { exitCodes: { kUnfinishedTopLevelAwait } } = internalBinding('errors');
+const { exitCodes: { kUnsettledTopLevelAwait } } = internalBinding('errors');
 const { URL } = require('internal/url');
 const { canParse: URLCanParse } = internalBinding('url');
 const { receiveMessageOnPort } = require('worker_threads');
@@ -146,8 +146,8 @@ class Hooks {
    * loader (user-land) to the worker.
    */
   async register(urlOrSpecifier, parentURL, data) {
-    const moduleLoader = require('internal/process/esm_loader').esmLoader;
-    const keyedExports = await moduleLoader.import(
+    const cascadedLoader = require('internal/modules/esm/loader').getOrInitializeCascadedLoader();
+    const keyedExports = await cascadedLoader.import(
       urlOrSpecifier,
       parentURL,
       kEmptyObject,
@@ -615,7 +615,7 @@ class HooksProxy {
     } while (response == null);
     debug('got sync response from worker', { method, args });
     if (response.message.status === 'never-settle') {
-      process.exit(kUnfinishedTopLevelAwait);
+      process.exit(kUnsettledTopLevelAwait);
     } else if (response.message.status === 'exit') {
       process.exit(response.message.body);
     }

lib/internal/modules/esm/loader.js

@@ -20,7 +20,7 @@ const {
   ERR_UNKNOWN_MODULE_FORMAT,
 } = require('internal/errors').codes;
 const { getOptionValue } = require('internal/options');
-const { pathToFileURL, isURL } = require('internal/url');
+const { isURL } = require('internal/url');
 const { emitExperimentalWarning } = require('internal/util');
 const {
   getDefaultConditions,
@@ -85,11 +85,6 @@ class ModuleLoader {
    */
   #defaultConditions = getDefaultConditions();
 
-  /**
-   * The index for assigning unique URLs to anonymous module evaluation
-   */
-  evalIndex = 0;
-
   /**
    * Registry of resolved specifiers
    */
@@ -187,10 +182,7 @@ class ModuleLoader {
     }
   }
 
-  async eval(
-    source,
-    url = pathToFileURL(`${process.cwd()}/[eval${++this.evalIndex}]`).href,
-  ) {
+  async eval(source, url, isEntryPoint = false) {
     const evalInstance = (url) => {
       const { ModuleWrap } = internalBinding('module_wrap');
       const { registerModule } = require('internal/modules/esm/utils');
@@ -209,11 +201,12 @@ class ModuleLoader {
     const job = new ModuleJob(
       this, url, undefined, evalInstance, false, false);
     this.loadCache.set(url, undefined, job);
-    const { module } = await job.run();
+    const { module } = await job.run(isEntryPoint);
 
     return {
       __proto__: null,
       namespace: module.getNamespace(),
+      module,
     };
   }
 
@@ -318,9 +311,9 @@ class ModuleLoader {
    *                                                  module import.
    * @returns {Promise<ModuleExports>}
    */
-  async import(specifier, parentURL, importAttributes) {
+  async import(specifier, parentURL, importAttributes, isEntryPoint = false) {
     const moduleJob = await this.getModuleJob(specifier, parentURL, importAttributes);
-    const { module } = await moduleJob.run();
+    const { module } = await moduleJob.run(isEntryPoint);
     return module.getNamespace();
   }
 
@@ -568,6 +561,23 @@ function getHooksProxy() {
   return hooksProxy;
 }
 
+let cascadedLoader;
+
+/**
+ * This is a singleton ESM loader that integrates the loader hooks, if any.
+ * It it used by other internal built-ins when they need to load ESM code
+ * while also respecting hooks.
+ * When built-ins need access to this loader, they should do
+ * require('internal/module/esm/loader').getOrInitializeCascadedLoader()
+ * lazily only right before the loader is actually needed, and don't do it
+ * in the top-level, to avoid circular dependencies.
+ * @returns {ModuleLoader}
+ */
+function getOrInitializeCascadedLoader() {
+  cascadedLoader ??= createModuleLoader();
+  return cascadedLoader;
+}
+
 /**
  * Register a single loader programmatically.
  * @param {string|import('url').URL} specifier
@@ -598,12 +608,11 @@ function getHooksProxy() {
  * ```
  */
 function register(specifier, parentURL = undefined, options) {
-  const moduleLoader = require('internal/process/esm_loader').esmLoader;
   if (parentURL != null && typeof parentURL === 'object' && !isURL(parentURL)) {
     options = parentURL;
     parentURL = options.parentURL;
   }
-  moduleLoader.register(
+  getOrInitializeCascadedLoader().register(
     specifier,
     parentURL ?? 'data:',
     options?.data,
@@ -614,5 +623,6 @@ function register(specifier, parentURL = undefined, options) {
 module.exports = {
   createModuleLoader,
   getHooksProxy,
+  getOrInitializeCascadedLoader,
   register,
 };

lib/internal/modules/esm/module_job.js

@@ -17,10 +17,15 @@ const {
   StringPrototypeIncludes,
   StringPrototypeSplit,
   StringPrototypeStartsWith,
+  globalThis,
 } = primordials;
 
 const { ModuleWrap } = internalBinding('module_wrap');
-
+const {
+  privateSymbols: {
+    entry_point_module_private_symbol,
+  },
+} = internalBinding('util');
 const { decorateErrorStack, kEmptyObject } = require('internal/util');
 const {
   getSourceMapsEnabled,
@@ -213,8 +218,11 @@ class ModuleJob {
     return { __proto__: null, module: this.module };
   }
 
-  async run() {
+  async run(isEntryPoint = false) {
     await this.instantiate();
+    if (isEntryPoint) {
+      globalThis[entry_point_module_private_symbol] = this.module;
+    }
     const timeout = -1;
     const breakOnSigint = false;
     setHasStartedUserESMExecution();

lib/internal/modules/esm/translators.js

@@ -55,7 +55,6 @@ const {
 const { maybeCacheSourceMap } = require('internal/source_map/source_map_cache');
 const moduleWrap = internalBinding('module_wrap');
 const { ModuleWrap } = moduleWrap;
-const asyncESM = require('internal/process/esm_loader');
 const { emitWarningSync } = require('internal/process/warning');
 const { internalCompileFunction } = require('internal/vm');
 const {
@@ -157,7 +156,8 @@ function errPath(url) {
  * @returns {Promise<import('internal/modules/esm/loader.js').ModuleExports>} The imported module.
  */
 async function importModuleDynamically(specifier, { url }, attributes) {
-  return asyncESM.esmLoader.import(specifier, url, attributes);
+  const cascadedLoader = require('internal/modules/esm/loader').getOrInitializeCascadedLoader();
+  return cascadedLoader.import(specifier, url, attributes);
 }
 
 // Strategy for loading a standard JavaScript module.
@@ -243,6 +243,7 @@ function loadCJSModule(module, source, url, filename) {
 
   const compiledWrapper = compileResult.function;
 
+  const cascadedLoader = require('internal/modules/esm/loader').getOrInitializeCascadedLoader();
   const __dirname = dirname(filename);
   // eslint-disable-next-line func-name-matching,func-style
   const requireFn = function require(specifier) {
@@ -261,7 +262,7 @@ function loadCJSModule(module, source, url, filename) {
       }
       specifier = `${pathToFileURL(path)}`;
     }
-    const job = asyncESM.esmLoader.getModuleJobSync(specifier, url, importAttributes);
+    const job = cascadedLoader.getModuleJobSync(specifier, url, importAttributes);
     job.runSync();
     return cjsCache.get(job.url).exports;
   };
@@ -272,7 +273,7 @@ function loadCJSModule(module, source, url, filename) {
         specifier = `${pathToFileURL(path)}`;
       }
     }
-    const { url: resolvedURL } = asyncESM.esmLoader.resolveSync(specifier, url, kEmptyObject);
+    const { url: resolvedURL } = cascadedLoader.resolveSync(specifier, url, kEmptyObject);
     return StringPrototypeStartsWith(resolvedURL, 'file://') ? fileURLToPath(resolvedURL) : resolvedURL;
   });
   setOwnProperty(requireFn, 'main', process.mainModule);

lib/internal/modules/esm/utils.js

@@ -32,7 +32,6 @@ const {
 const {
   emitExperimentalWarning,
   getCWDURL,
-  getLazy,
 } = require('internal/util');
 const {
   setImportModuleDynamicallyCallback,
@@ -181,9 +180,6 @@ function initializeImportMetaObject(symbol, meta) {
     }
   }
 }
-const getCascadedLoader = getLazy(
-  () => require('internal/process/esm_loader').esmLoader,
-);
 
 /**
  * Proxy the dynamic import to the default loader.
@@ -194,7 +190,8 @@ const getCascadedLoader = getLazy(
  */
 function defaultImportModuleDynamically(specifier, attributes, referrerName) {
   const parentURL = normalizeReferrerURL(referrerName);
-  return getCascadedLoader().import(specifier, parentURL, attributes);
+  const cascadedLoader = require('internal/modules/esm/loader').getOrInitializeCascadedLoader();
+  return cascadedLoader.import(specifier, parentURL, attributes);
 }
 
 /**
@@ -263,10 +260,10 @@ async function initializeHooks() {
   const customLoaderURLs = getOptionValue('--experimental-loader');
 
   const { Hooks } = require('internal/modules/esm/hooks');
-  const esmLoader = require('internal/process/esm_loader').esmLoader;
+  const cascadedLoader = require('internal/modules/esm/loader').getOrInitializeCascadedLoader();
 
   const hooks = new Hooks();
-  esmLoader.setCustomizations(hooks);
+  cascadedLoader.setCustomizations(hooks);
 
   // We need the loader customizations to be set _before_ we start invoking
   // `--require`, otherwise loops can happen because a `--require` script