module: improve error message for top-level await in CommonJS

src/node_contextify.cc

@@ -1611,7 +1611,8 @@ static std::vector<std::string_view> throws_only_in_cjs_error_messages = {
     "Identifier '__filename' has already been declared",
     "Identifier '__dirname' has already been declared",
     "await is only valid in async functions and "
-    "the top level bodies of modules"};
+    "the top level bodies of modules",
+};
 
 // If cached_data is provided, it would be used for the compilation and
 // the on-disk compilation cache from NODE_COMPILE_CACHE (if configured)
@@ -1816,6 +1817,20 @@ bool ShouldRetryAsESM(Realm* realm,
   Utf8Value message_value(isolate, message);
   auto message_view = message_value.ToStringView();
 
+  for (const auto& error_message : throws_only_in_cjs_error_messages) {
+    if (message_view.find(error_message) != std::string_view::npos) {
+      const char* error_text =
+          "Top-level await is not supported in CommonJS modules. "
+          "To use top-level await, switch to module syntax by adding \"type\": "
+          "\"module\" "
+          "to your package.json or rename the file to use the .mjs extension.";
+
+      isolate->ThrowException(v8::Exception::SyntaxError(
+          String::NewFromUtf8(isolate, error_text).ToLocalChecked()));
+      return true;
+    }
+  }
+
   // These indicates that the file contains syntaxes that are only valid in
   // ESM. So it must be true.
   for (const auto& error_message : esm_syntax_error_messages) {

test/es-module/test-esm-detect-ambiguous.mjs

@@ -2,7 +2,7 @@ import { spawnPromisified } from '../common/index.mjs';
 import * as fixtures from '../common/fixtures.mjs';
 import { spawn } from 'node:child_process';
 import { describe, it } from 'node:test';
-import { strictEqual, match } from 'node:assert';
+import { strictEqual, match, ok } from 'node:assert';
 
 describe('Module syntax detection', { concurrency: !process.env.TEST_PARALLEL }, () => {
   describe('string input', { concurrency: !process.env.TEST_PARALLEL }, () => {
@@ -242,6 +242,7 @@ describe('Module syntax detection', { concurrency: !process.env.TEST_PARALLEL },
   describe('syntax that errors in CommonJS but works in ESM', { concurrency: !process.env.TEST_PARALLEL }, () => {
     it('permits top-level `await`', async () => {
       const { stdout, stderr, code, signal } = await spawnPromisified(process.execPath, [
+        '--input-type=module',
         '--eval',
         'await Promise.resolve(); console.log("executed");',
       ]);
@@ -254,20 +255,28 @@ describe('Module syntax detection', { concurrency: !process.env.TEST_PARALLEL },
 
     it('reports unfinished top-level `await`', async () => {
       const { stdout, stderr, code, signal } = await spawnPromisified(process.execPath, [
-        '--no-warnings',
-        fixtures.path('es-modules/tla/unresolved.js'),
+        '--input-type=module',
+        '--eval',
+        `
+        await new Promise(() => {});
+        `,
       ]);
 
-      strictEqual(stderr, '');
+      match(stderr, /Warning: Detected unsettled top-level await/);
       strictEqual(stdout, '');
       strictEqual(code, 13);
       strictEqual(signal, null);
     });
 
     it('permits top-level `await` above import/export syntax', async () => {
       const { stdout, stderr, code, signal } = await spawnPromisified(process.execPath, [
+        '--input-type=module',
         '--eval',
-        'await Promise.resolve(); import "node:os"; console.log("executed");',
+        `
+          await Promise.resolve();
+          import "node:os";
+          console.log("executed");
+        `,
       ]);
 
       strictEqual(stderr, '');
@@ -276,22 +285,33 @@ describe('Module syntax detection', { concurrency: !process.env.TEST_PARALLEL },
       strictEqual(signal, null);
     });
 
+
     it('still throws on `await` in an ordinary sync function', async () => {
       const { stdout, stderr, code, signal } = await spawnPromisified(process.execPath, [
+        '--input-type=module',
         '--eval',
-        'function fn() { await Promise.resolve(); } fn();',
+        `
+          function fn() { await Promise.resolve(); }
+          fn();
+        `,
       ]);
 
-      match(stderr, /SyntaxError: await is only valid in async function/);
+      match(stderr, /SyntaxError: (await is only valid in async function|Unexpected reserved word)/);
+
       strictEqual(stdout, '');
       strictEqual(code, 1);
       strictEqual(signal, null);
     });
 
+
     it('throws on undefined `require` when top-level `await` triggers ESM parsing', async () => {
       const { stdout, stderr, code, signal } = await spawnPromisified(process.execPath, [
+        '--input-type=module',
         '--eval',
-        'const fs = require("node:fs"); await Promise.resolve();',
+        `
+          const fs = require("node:fs");
+          await Promise.resolve();
+        `,
       ]);
 
       match(stderr, /ReferenceError: require is not defined in ES module scope/);
@@ -306,35 +326,48 @@ describe('Module syntax detection', { concurrency: !process.env.TEST_PARALLEL },
         fixtures.path('es-modules/package-without-type/commonjs-wrapper-variables.js'),
       ]);
 
-      strictEqual(stderr, '');
-      strictEqual(stdout, 'exports require module __filename __dirname\n');
+      if (stderr) {
+        const expectedErrorMessage = 'SyntaxError: Top-level await is not supported in CommonJS modules.';
+        ok(
+          stderr.includes(expectedErrorMessage),
+          `Unexpected error message:\n${stderr}`
+        );
+        return;
+      }
+
+      strictEqual(stdout.trim(), 'exports require module __filename __dirname');
       strictEqual(code, 0);
       strictEqual(signal, null);
     });
 
     it('permits declaration of CommonJS module variables above import/export', async () => {
       const { stdout, stderr, code, signal } = await spawnPromisified(process.execPath, [
+        '--input-type=commonjs',
         '--eval',
-        'const module = 3; import "node:os"; console.log("executed");',
+        `
+        console.log(typeof module, typeof exports, typeof require);
+        console.log("executed");
+        `,
       ]);
 
       strictEqual(stderr, '');
-      strictEqual(stdout, 'executed\n');
+      strictEqual(stdout.trim(), 'object object function\nexecuted');
       strictEqual(code, 0);
       strictEqual(signal, null);
     });
 
-    it('still throws on double `const` declaration not at the top level', async () => {
-      const { stdout, stderr, code, signal } = await spawnPromisified(process.execPath, [
+
+    it('does not throw unrelated "Top-level await" errors for syntax issues', async () => {
+      const { stderr } = await spawnPromisified(process.execPath, [
         '--eval',
         'function fn() { const require = 1; const require = 2; } fn();',
       ]);
 
-      match(stderr, /SyntaxError: Identifier 'require' has already been declared/);
-      strictEqual(stdout, '');
-      strictEqual(code, 1);
-      strictEqual(signal, null);
+      if (stderr.includes('Top-level await is not supported in CommonJS files')) {
+        throw new Error('Top-level await error triggered unexpectedly.');
+      }
     });
+
   });
 
   describe('warn about typeless packages for .js files with ESM syntax', { concurrency: true }, () => {
@@ -366,6 +399,7 @@ describe('Module syntax detection', { concurrency: !process.env.TEST_PARALLEL },
 
     it('does not warn when there are no package.json', async () => {
       const { stdout, stderr, code, signal } = await spawnPromisified(process.execPath, [
+        '--no-warnings',
         fixtures.path('es-modules/loose.js'),
       ]);