esm: improve error messages for ambiguous module syntax

Author: mag123c

lib/internal/modules/esm/module_job.js

@@ -3,7 +3,6 @@
 const {
   Array,
   ArrayPrototypeJoin,
-  ArrayPrototypeSome,
   FunctionPrototype,
   ObjectSetPrototypeOf,
   PromisePrototypeThen,
@@ -61,11 +60,14 @@ const CJSGlobalLike = [
   '__filename',
   '__dirname',
 ];
-const isCommonJSGlobalLikeNotDefinedError = (errorMessage) =>
-  ArrayPrototypeSome(
-    CJSGlobalLike,
-    (globalLike) => errorMessage === `${globalLike} is not defined`,
-  );
+const getUndefinedCJSGlobalLike = (errorMessage) => {
+  for (const globalLike of CJSGlobalLike) {
+    if (errorMessage === `${globalLike} is not defined`) {
+      return globalLike;
+    }
+  }
+  return null;
+};
 
 
 /**
@@ -75,11 +77,20 @@ const isCommonJSGlobalLikeNotDefinedError = (errorMessage) =>
  * @returns {void}
  */
 const explainCommonJSGlobalLikeNotDefinedError = (e, url, hasTopLevelAwait) => {
-  if (e?.name === 'ReferenceError' &&
-      isCommonJSGlobalLikeNotDefinedError(e.message)) {
+  const undefinedGlobal = getUndefinedCJSGlobalLike(e?.message);
+  if (e?.name === 'ReferenceError' && undefinedGlobal !== null) {
 
     if (hasTopLevelAwait) {
-      e.message = `Cannot determine intended module format because both require() and top-level await are present. If the code is intended to be CommonJS, wrap await in an async function. If the code is intended to be an ES module, replace require() with import.`;
+      let advice = '';
+      if (undefinedGlobal === 'require') {
+        advice = 'replace require() with import';
+      } else if (undefinedGlobal === 'module' || undefinedGlobal === 'exports') {
+        advice = 'use export instead of module.exports/exports';
+      } else if (undefinedGlobal === '__filename' || undefinedGlobal === '__dirname') {
+        advice = 'use import.meta.url instead';
+      }
+
+      e.message = `Cannot determine intended module format because both ${undefinedGlobal} and top-level await are present. If the code is intended to be CommonJS, wrap await in an async function. If the code is intended to be an ES module, ${advice}.`;
       e.code = 'ERR_AMBIGUOUS_MODULE_SYNTAX';
       return;
     }

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

@@ -283,7 +283,7 @@ describe('Module syntax detection', { concurrency: !process.env.TEST_PARALLEL },
 
       match(
         stderr,
-        /ReferenceError: Cannot determine intended module format because both require\(\) and top-level await are present\. If the code is intended to be CommonJS, wrap await in an async function\. If the code is intended to be an ES module, replace require\(\) with import\./
+        /ReferenceError: Cannot determine intended module format because both require and top-level await are present\. If the code is intended to be CommonJS, wrap await in an async function\. If the code is intended to be an ES module, replace require\(\) with import\./
       );
       strictEqual(stdout, '');
       strictEqual(code, 1);
@@ -432,15 +432,32 @@ describe('cjs & esm ambiguous syntax case', () => {
     const { stderr, code, signal } = await spawnPromisified(
       process.execPath,
       [
-        '--input-type=module',
         '--eval',
-        `await 1;\nconst fs = require('fs');`,
+        `const fs = require('fs');\nawait 1;`,
       ]
     );
 
     match(
       stderr,
-      /ReferenceError: Cannot determine intended module format because both require\(\) and top-level await are present\. If the code is intended to be CommonJS, wrap await in an async function\. If the code is intended to be an ES module, replace require\(\) with import\./
+      /ReferenceError: Cannot determine intended module format because both require and top-level await are present\. If the code is intended to be CommonJS, wrap await in an async function\. If the code is intended to be an ES module, replace require\(\) with import\./
+    );
+
+    strictEqual(code, 1);
+    strictEqual(signal, null);
+  });
+
+  it('should throw an ambiguous syntax error when using top-level await with exports', async () => {
+    const { stderr, code, signal } = await spawnPromisified(
+      process.execPath,
+      [
+        '--eval',
+        `exports.foo = 'bar';\nawait 1;`,
+      ]
+    );
+
+    match(
+      stderr,
+      /ReferenceError: Cannot determine intended module format because both exports and top-level await are present\. If the code is intended to be CommonJS, wrap await in an async function\. If the code is intended to be an ES module, use export instead of module\.exports\/exports\./
     );
 
     strictEqual(code, 1);