Breaking: Switch to ESM (fixes #70) (#71)

* Chore: Update devDeps.

* Chore: Lint according to latest config

* Breaking: Switch to ESM; also adds eslint-plugin-jsdoc for linter

* Fix: Sync with eslint-visitor-keys, including fixing cjs linting

* Update package.json

Co-authored-by: Nicholas C. Zakas <[email protected]>

* Test: Drop Node 13, 10, 8 tests, and add 16, 12.22.0

* Docs: Add comment to explain shelljs command

* Refactor: Apply new API and ESM changes

* Chore: Update devDeps.

* Docs: Update espree usage in README

* Test: Add CJS file

* Update README.md

Co-authored-by: Nicholas C. Zakas <[email protected]>

* Fix: Avoid named imports of CJS modules

* Fix: For browser compatibility, avoid package.json file-reading attempt

* Refactor: Drop `fs` from Rollup now that not in use

* Fix: Stop re-exporting Scope child classes and only export `Scope`

* Fix: Re-export Reference, Definition, and PatternVisitor

* Update Makefile.js

Co-authored-by: Milos Djermanovic <[email protected]>

* Update tests/commonjs.cjs

Co-authored-by: Brandon Mills <[email protected]>

Co-authored-by: Nicholas C. Zakas <[email protected]>
Co-authored-by: Milos Djermanovic <[email protected]>
Co-authored-by: Brandon Mills <[email protected]>

.editorconfig

@@ -0,0 +1,15 @@
+; EditorConfig file: https://EditorConfig.org
+; Install the "EditorConfig" plugin into your editor to use
+
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 4
+trim_trailing_whitespace = true
+
+[package.json]
+indent_size = 2

.eslintrc.cjs

@@ -0,0 +1,30 @@
+"use strict";
+
+module.exports = {
+    root: true,
+    extends: [
+        "eslint",
+        "plugin:node/recommended-module"
+    ],
+    parserOptions: {
+        sourceType: "module",
+        ecmaVersion: "2020"
+    },
+    overrides: [
+        {
+            files: ["tests/**/*"],
+            env: {
+                mocha: true
+            }
+        },
+        {
+            files: ["*.cjs"],
+            extends: ["eslint", "plugin:node/recommended-script"],
+            parserOptions: {
+                sourceType: "script",
+                ecmaVersion: "2020"
+            }
+        }
+    ],
+    ignorePatterns: ["/dist", "/coverage"]
+};

.github/workflows/ci.yml

@@ -25,7 +25,7 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest]
-        node: [14.x, 13.x, 12.x, 10.x, 8.x]
+        node: [16.x, 14.x, 12.x, "12.22.0"]
     runs-on: ${{ matrix.os }}
     steps:
     - uses: actions/checkout@v2

.gitignore

@@ -8,3 +8,4 @@ npm-debug.log
 /.vscode
 .sublimelinterrc
 .eslint-release-info.json
+dist

Makefile.js

@@ -6,42 +6,51 @@
  */
 /* global echo, exec, exit, set, target */
 
-"use strict";
-
 /* eslint no-console: 0*/
 //------------------------------------------------------------------------------
 // Requirements
 //------------------------------------------------------------------------------
 
-require("shelljs/make");
-set("+e");
+import path from "path";
+import { fileURLToPath } from "url";
+
+import "shelljs/make.js";
+import checker from "npm-license";
+
+const dirname = path.dirname(fileURLToPath(import.meta.url));
 
-const checker = require("npm-license");
+// `shelljs/make.js` global command to unset any `set('-e')` (to exit upon
+//    first error)
+set("+e");
 
 //------------------------------------------------------------------------------
 // Settings
 //------------------------------------------------------------------------------
 
 const OPEN_SOURCE_LICENSES = [
-    /MIT/, /BSD/, /Apache/, /ISC/, /WTF/, /Public Domain/
+    /MIT/u, /BSD/u, /Apache/u, /ISC/u, /WTF/u, /Public Domain/u
 ];
 
 //------------------------------------------------------------------------------
 // Data
 //------------------------------------------------------------------------------
 
 const NODE = "node",
-    NODE_MODULES = "./node_modules/",
+    NODE_MODULES = "./node_modules",
 
     // Utilities - intentional extra space at the end of each string
-    MOCHA = `${NODE_MODULES}mocha/bin/_mocha `,
+    MOCHA = `${NODE_MODULES}/mocha/bin/_mocha `,
     ESLINT = `${NODE} ${NODE_MODULES}/eslint/bin/eslint `,
-    ISTANBUL = `${NODE} ${NODE_MODULES}/istanbul/lib/cli.js `,
+
+    // If switching back to Istanbul when may be working with ESM
+    // ISTANBUL = `${NODE} ${NODE_MODULES}/istanbul/lib/cli.js `,
+    C8 = `${NODE} ${NODE_MODULES}/c8/bin/c8.js`,
 
     // Files
     MAKEFILE = "./Makefile.js",
     JS_FILES = "lib/**/*.js",
-    TEST_FILES = "tests/*.js";
+    TEST_FILES = "tests/*.js",
+    CJS_TEST_FILES = "tests/*.cjs";
 
 //------------------------------------------------------------------------------
 // Tasks
@@ -73,14 +82,26 @@ target.lint = function() {
         errors++;
     }
 
+    echo("Validating CJS JavaScript test files");
+    lastReturn = exec(ESLINT + CJS_TEST_FILES);
+    if (lastReturn.code !== 0) {
+        errors++;
+    }
+
     if (errors) {
         exit(1);
     }
 };
 
 target.test = function() {
     let errors = 0;
-    const lastReturn = exec(`${ISTANBUL} cover ${MOCHA} -- -R progress -c ${TEST_FILES}`);
+    let lastReturn = exec(`${NODE} ${MOCHA} -- -R progress -c ${CJS_TEST_FILES}`);
+
+    if (lastReturn.code !== 0) {
+        errors++;
+    }
+
+    lastReturn = exec(`${C8} ${MOCHA} -- -R progress -c ${TEST_FILES}`);
 
     if (lastReturn.code !== 0) {
         errors++;
@@ -116,7 +137,7 @@ target.checkLicenses = function() {
     echo("Validating licenses");
 
     checker.init({
-        start: __dirname
+        start: dirname
     }, deps => {
         const impermissible = Object.keys(deps).map(dependency => ({
             name: dependency,

README.md

@@ -2,35 +2,47 @@
 
 ESLint Scope is the [ECMAScript](http://www.ecma-international.org/publications/standards/Ecma-262.htm) scope analyzer used in ESLint. It is a fork of [escope](http://github.com/estools/escope).
 
-## Usage
-
-Install:
+## Install
 
 ```
 npm i eslint-scope --save
 ```
 
+## 📖 Usage
+
+To use in an ESM file:
+
+```js
+import * as eslintScope from 'eslint-scope';
+```
+
+To use in a CommonJS file:
+
+```js
+const eslintScope = require('eslint-scope');
+```
+
 Example:
 
 ```js
-var eslintScope = require('eslint-scope');
-var espree = require('espree');
-var estraverse = require('estraverse');
+import * as eslintScope from 'eslint-scope';
+import * as espree from 'espree';
+import estraverse from 'estraverse';
 
-var ast = espree.parse(code, { range: true });
-var scopeManager = eslintScope.analyze(ast);
+const ast = espree.parse(code, { range: true });
+const scopeManager = eslintScope.analyze(ast);
 
-var currentScope = scopeManager.acquire(ast);   // global scope
+const currentScope = scopeManager.acquire(ast);   // global scope
 
 estraverse.traverse(ast, {
-    enter: function(node, parent) {
+    enter (node, parent) {
         // do stuff
 
         if (/Function/.test(node.type)) {
             currentScope = scopeManager.acquire(node);  // get current function scope
         }
     },
-    leave: function(node, parent) {
+    leave(node, parent) {
         if (/Function/.test(node.type)) {
             currentScope = currentScope.upper;  // set to parent scope
         }

lib/definition.js

@@ -21,18 +21,17 @@
   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
   THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
-"use strict";
 
-const Variable = require("./variable");
+import Variable from "./variable.js";
 
 /**
- * @class Definition
+ * @constructor Definition
  */
 class Definition {
     constructor(type, name, node, parent, index, kind) {
 
         /**
-         * @member {String} Definition#type - type of the occurrence (e.g. "Parameter", "Variable", ...).
+         * @member {string} Definition#type - type of the occurrence (e.g. "Parameter", "Variable", ...).
          */
         this.type = type;
 
@@ -52,19 +51,19 @@ class Definition {
         this.parent = parent;
 
         /**
-         * @member {Number?} Definition#index - the index in the declaration statement.
+         * @member {number?} Definition#index - the index in the declaration statement.
          */
         this.index = index;
 
         /**
-         * @member {String?} Definition#kind - the kind of the declaration statement.
+         * @member {string?} Definition#kind - the kind of the declaration statement.
          */
         this.kind = kind;
     }
 }
 
 /**
- * @class ParameterDefinition
+ * @constructor ParameterDefinition
  */
 class ParameterDefinition extends Definition {
     constructor(name, node, index, rest) {
@@ -78,7 +77,7 @@ class ParameterDefinition extends Definition {
     }
 }
 
-module.exports = {
+export {
     ParameterDefinition,
     Definition
 };