From 695d78014fc0d1454c5d71b2cddf0315dc946e7b Mon Sep 17 00:00:00 2001
From: Geoffrey Booth <webmaster@geoffreybooth.com>
Date: Thu, 18 Apr 2019 00:18:11 -0700
Subject: [PATCH] esm: add utility method for detecting ES module syntax

---
 doc/api/modules.md                            | 24 ++++++++++
 lib/internal/modules/cjs/loader.js            | 40 +++++++++++++++++
 .../test-esm-contains-module-syntax.js        | 44 +++++++++++++++++++
 .../ambiguous-with-import-expression.js       |  3 ++
 .../detect/cjs-with-import-expression.js      |  5 +++
 .../detect/cjs-with-property-named-export.js  | 11 +++++
 .../detect/cjs-with-property-named-import.js  | 14 ++++++
 .../es-modules/detect/cjs-with-require.js     |  3 ++
 .../cjs-with-string-containing-import.js      |  7 +++
 .../detect/esm-with-export-statement.js       |  6 +++
 .../detect/esm-with-import-expression.js      |  5 +++
 .../detect/esm-with-import-statement.js       |  2 +
 .../esm-with-indented-import-statement.js     |  2 +
 test/fixtures/es-modules/detect/package.json  |  1 +
 .../es-modules/detect/print-version.js        |  1 +
 .../es-modules/detect/syntax-error.js         |  2 +
 16 files changed, 170 insertions(+)
 create mode 100644 test/es-module/test-esm-contains-module-syntax.js
 create mode 100644 test/fixtures/es-modules/detect/ambiguous-with-import-expression.js
 create mode 100644 test/fixtures/es-modules/detect/cjs-with-import-expression.js
 create mode 100644 test/fixtures/es-modules/detect/cjs-with-property-named-export.js
 create mode 100644 test/fixtures/es-modules/detect/cjs-with-property-named-import.js
 create mode 100644 test/fixtures/es-modules/detect/cjs-with-require.js
 create mode 100644 test/fixtures/es-modules/detect/cjs-with-string-containing-import.js
 create mode 100644 test/fixtures/es-modules/detect/esm-with-export-statement.js
 create mode 100644 test/fixtures/es-modules/detect/esm-with-import-expression.js
 create mode 100644 test/fixtures/es-modules/detect/esm-with-import-statement.js
 create mode 100644 test/fixtures/es-modules/detect/esm-with-indented-import-statement.js
 create mode 100644 test/fixtures/es-modules/detect/package.json
 create mode 100644 test/fixtures/es-modules/detect/print-version.js
 create mode 100644 test/fixtures/es-modules/detect/syntax-error.js

diff --git a/doc/api/modules.md b/doc/api/modules.md
index 9266d43f49..bbc1540a06 100644
--- a/doc/api/modules.md
+++ b/doc/api/modules.md
@@ -912,6 +912,29 @@ by the [module wrapper][]. To access it, require the `Module` module:
 const builtin = require('module').builtinModules;
 ```
 
+### module.containsModuleSyntax(source)
+<!-- YAML
+added: REPLACEME
+-->
+
+* `source` {string} JavaScript source code
+* Returns: {boolean}
+
+Detect whether input JavaScript source code contains [ECMAScript Module][]
+syntax, defined as `import` or `export` statements. Returns `true` as soon as
+the first `import` or `export` statement is encountered, or `false` if none are
+found. Note that dynamic `import()` is not an `import` statement.
+
+```js
+const { containsModuleSyntax } = require('module');
+
+containsModuleSyntax('import { fn } from "pkg"'); // true
+containsModuleSyntax('console.log(process.version)'); // false
+
+containsModuleSyntax('import "./file.mjs"'); // true
+containsModuleSyntax('import("./file.mjs")'); // false
+```
+
 ### module.createRequire(filename)
 <!-- YAML
 added: v12.2.0
@@ -957,6 +980,7 @@ requireUtil('./some-tool');
 [`createRequire()`]: #modules_module_createrequire_filename
 [`module` object]: #modules_the_module_object
 [`path.dirname()`]: path.html#path_path_dirname_path
+[ECMAScript Module]: esm.html
 [ECMAScript Modules]: esm.html
 [an error]: errors.html#errors_err_require_esm
 [exports shortcut]: #modules_exports_shortcut
diff --git a/lib/internal/modules/cjs/loader.js b/lib/internal/modules/cjs/loader.js
index 2798032fd9..7e4608cf75 100644
--- a/lib/internal/modules/cjs/loader.js
+++ b/lib/internal/modules/cjs/loader.js
@@ -879,6 +879,46 @@ function createRequire(filename) {
 
 Module.createRequire = createRequire;
 
+Module.containsModuleSyntax = (source) => {
+  // Detect whether input source code contains at least one `import` or `export`
+  // statement. This can be used by dependent utilities as a way of detecting ES
+  // module source code from Script/CommonJS source code. Since our detection is
+  // so simple, we can avoid needing to use Acorn for a full parse; we can
+  // detect import or export statements just from the tokens. Also as of this
+  // writing, Acorn doesn't support import() expressions as they are only Stage
+  // 3; yet Node already supports them.
+  const acorn = require('internal/deps/acorn/acorn/dist/acorn');
+  source = stripShebang(source);
+  source = stripBOM(source);
+  try {
+    let prevToken, prevPrevToken;
+    for (const { type: token } of acorn.tokenizer(source)) {
+      if (prevToken &&
+        // By definition import or export must be followed by another token.
+        (prevToken.keyword === 'import' || prevToken.keyword === 'export') &&
+        // Skip `import(`; look only for import statements, not expressions.
+        // import() expressions are allowed in both CommonJS and ES modules.
+        token.label !== '(' &&
+        // Also ensure that the keyword we just saw wasn't an allowed use
+        // of a reserved word as a property name; see
+        // test/fixtures/es-modules/detect/cjs-with-property-named-import.js.
+        !(prevPrevToken && prevPrevToken.label === '.') &&
+        token.label !== ':')
+        return true; // This source code contains ES module syntax.
+      prevPrevToken = prevToken;
+      prevToken = token;
+    }
+  } catch {
+    // If the tokenizer threw, there's a syntax error.
+    // Compile the script, this will throw with an informative error.
+    const vm = require('vm');
+    new vm.Script(source, { displayErrors: true });
+  }
+  // This source code does not contain ES module syntax.
+  // It may or may not be CommonJS, and it may or may not be valid syntax.
+  return false;
+};
+
 Module._initPaths = function() {
   var homeDir;
   var nodePath;
diff --git a/test/es-module/test-esm-contains-module-syntax.js b/test/es-module/test-esm-contains-module-syntax.js
new file mode 100644
index 0000000000..ce883a9e08
--- /dev/null
+++ b/test/es-module/test-esm-contains-module-syntax.js
@@ -0,0 +1,44 @@
+'use strict';
+
+require('../common');
+const { strictEqual, fail } = require('assert');
+const { readFileSync } = require('fs');
+
+const { containsModuleSyntax } = require('module');
+
+expect('esm-with-import-statement.js', 'module');
+expect('esm-with-export-statement.js', 'module');
+expect('esm-with-import-expression.js', 'module');
+expect('esm-with-indented-import-statement.js', 'module');
+
+expect('cjs-with-require.js', 'commonjs');
+expect('cjs-with-import-expression.js', 'commonjs');
+expect('cjs-with-property-named-import.js', 'commonjs');
+expect('cjs-with-property-named-export.js', 'commonjs');
+expect('cjs-with-string-containing-import.js', 'commonjs');
+
+expect('print-version.js', 'commonjs');
+expect('ambiguous-with-import-expression.js', 'commonjs');
+
+expect('syntax-error.js', 'Invalid or unexpected token', true);
+
+function expect(file, want, wantsError = false) {
+  const source = readFileSync(
+    require.resolve(`../fixtures/es-modules/detect/${file}`),
+    'utf8');
+  let isModule;
+  try {
+    isModule = containsModuleSyntax(source);
+  } catch (err) {
+    if (wantsError) {
+      return strictEqual(err.message, want);
+    } else {
+      return fail(
+        `Expected ${file} to throw '${want}'; received '${err.message}'`);
+    }
+  }
+  if (wantsError)
+    return fail(`Expected ${file} to throw '${want}'; no error was thrown`);
+  else
+    return strictEqual((isModule ? 'module' : 'commonjs'), want);
+}
diff --git a/test/fixtures/es-modules/detect/ambiguous-with-import-expression.js b/test/fixtures/es-modules/detect/ambiguous-with-import-expression.js
new file mode 100644
index 0000000000..8513a2fe09
--- /dev/null
+++ b/test/fixtures/es-modules/detect/ambiguous-with-import-expression.js
@@ -0,0 +1,3 @@
+(async () => {
+  await import('./print-version.js');
+})();
diff --git a/test/fixtures/es-modules/detect/cjs-with-import-expression.js b/test/fixtures/es-modules/detect/cjs-with-import-expression.js
new file mode 100644
index 0000000000..4ca064ff0f
--- /dev/null
+++ b/test/fixtures/es-modules/detect/cjs-with-import-expression.js
@@ -0,0 +1,5 @@
+const { version } = require('process');
+
+(async () => {
+  await import('./print-version.js');
+})();
diff --git a/test/fixtures/es-modules/detect/cjs-with-property-named-export.js b/test/fixtures/es-modules/detect/cjs-with-property-named-export.js
new file mode 100644
index 0000000000..4389e477ad
--- /dev/null
+++ b/test/fixtures/es-modules/detect/cjs-with-property-named-export.js
@@ -0,0 +1,11 @@
+// See ./cjs-with-property-named-import.js
+
+global.export = 3;
+
+global['export'] = 3;
+
+const obj = {
+export: 3 // Specifically at column 0, to try to trick the detector
+}
+
+console.log(require('process').version);
diff --git a/test/fixtures/es-modules/detect/cjs-with-property-named-import.js b/test/fixtures/es-modules/detect/cjs-with-property-named-import.js
new file mode 100644
index 0000000000..8dec066037
--- /dev/null
+++ b/test/fixtures/es-modules/detect/cjs-with-property-named-import.js
@@ -0,0 +1,14 @@
+// In JavaScript, reserved words cannot be identifiers (the `foo` in `var foo`)
+// but they can be properties (`obj.foo`). This file checks that the `import`
+// reserved word isn't incorrectly detected as a keyword. For more info see:
+// https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Lexical_grammar#Reserved_word_usage
+
+global.import = 3;
+
+global['import'] = 3;
+
+const obj = {
+import: 3 // Specifically at column 0, to try to trick the detector
+}
+
+console.log(require('process').version);
diff --git a/test/fixtures/es-modules/detect/cjs-with-require.js b/test/fixtures/es-modules/detect/cjs-with-require.js
new file mode 100644
index 0000000000..195ad7956a
--- /dev/null
+++ b/test/fixtures/es-modules/detect/cjs-with-require.js
@@ -0,0 +1,3 @@
+const { version } = require('process');
+
+console.log(version);
diff --git a/test/fixtures/es-modules/detect/cjs-with-string-containing-import.js b/test/fixtures/es-modules/detect/cjs-with-string-containing-import.js
new file mode 100644
index 0000000000..7f8319a90e
--- /dev/null
+++ b/test/fixtures/es-modules/detect/cjs-with-string-containing-import.js
@@ -0,0 +1,7 @@
+const { version } = require('process');
+
+const sneakyString = `
+import { version } from 'process';
+`;
+
+console.log(version);
diff --git a/test/fixtures/es-modules/detect/esm-with-export-statement.js b/test/fixtures/es-modules/detect/esm-with-export-statement.js
new file mode 100644
index 0000000000..aed6f05d72
--- /dev/null
+++ b/test/fixtures/es-modules/detect/esm-with-export-statement.js
@@ -0,0 +1,6 @@
+const version = process.version;
+
+export default version;
+
+console.log(version);
+
diff --git a/test/fixtures/es-modules/detect/esm-with-import-expression.js b/test/fixtures/es-modules/detect/esm-with-import-expression.js
new file mode 100644
index 0000000000..83ed565b65
--- /dev/null
+++ b/test/fixtures/es-modules/detect/esm-with-import-expression.js
@@ -0,0 +1,5 @@
+import { version } from 'process';
+
+(async () => {
+  await import('./print-version.js');
+})();
diff --git a/test/fixtures/es-modules/detect/esm-with-import-statement.js b/test/fixtures/es-modules/detect/esm-with-import-statement.js
new file mode 100644
index 0000000000..fee4151c85
--- /dev/null
+++ b/test/fixtures/es-modules/detect/esm-with-import-statement.js
@@ -0,0 +1,2 @@
+import { version } from 'process';
+console.log(version);
diff --git a/test/fixtures/es-modules/detect/esm-with-indented-import-statement.js b/test/fixtures/es-modules/detect/esm-with-indented-import-statement.js
new file mode 100644
index 0000000000..ca9d4edc0f
--- /dev/null
+++ b/test/fixtures/es-modules/detect/esm-with-indented-import-statement.js
@@ -0,0 +1,2 @@
+  import { version } from 'process';
+  console.log(version);
diff --git a/test/fixtures/es-modules/detect/package.json b/test/fixtures/es-modules/detect/package.json
new file mode 100644
index 0000000000..0967ef424b
--- /dev/null
+++ b/test/fixtures/es-modules/detect/package.json
@@ -0,0 +1 @@
+{}
diff --git a/test/fixtures/es-modules/detect/print-version.js b/test/fixtures/es-modules/detect/print-version.js
new file mode 100644
index 0000000000..557b2f103e
--- /dev/null
+++ b/test/fixtures/es-modules/detect/print-version.js
@@ -0,0 +1 @@
+console.log(process.version);
diff --git a/test/fixtures/es-modules/detect/syntax-error.js b/test/fixtures/es-modules/detect/syntax-error.js
new file mode 100644
index 0000000000..398e47a16e
--- /dev/null
+++ b/test/fixtures/es-modules/detect/syntax-error.js
@@ -0,0 +1,2 @@
+const str = 'import
+var foo = 3;