Breaking: Strict package exports (refs #13654) (#14706)

* Breaking: Strict package exports (refs #13654)

* Update docs

* Fix linting errors

* Update docs/developer-guide/nodejs-api.md

Co-authored-by: Milos Djermanovic <milos.djermanovic@gmail.com>

* Update docs/developer-guide/nodejs-api.md

Co-authored-by: Milos Djermanovic <milos.djermanovic@gmail.com>

Co-authored-by: Milos Djermanovic <milos.djermanovic@gmail.com>

.eslintrc.js

@@ -110,6 +110,7 @@ module.exports = {
         // Restrict relative path imports
         {
             files: ["lib/*"],
+            excludedFiles: ["lib/unsupported-api.js"],
             rules: {
                 "node/no-restricted-require": ["error", [
                     ...createInternalFilesPatterns()

lib/api.js

@@ -5,30 +5,22 @@
 
 "use strict";
 
-const { CLIEngine } = require("./cli-engine");
+//-----------------------------------------------------------------------------
+// Requirements
+//-----------------------------------------------------------------------------
+
 const { ESLint } = require("./eslint");
 const { Linter } = require("./linter");
 const { RuleTester } = require("./rule-tester");
 const { SourceCode } = require("./source-code");
 
+//-----------------------------------------------------------------------------
+// Exports
+//-----------------------------------------------------------------------------
+
 module.exports = {
     Linter,
-    CLIEngine,
     ESLint,
     RuleTester,
     SourceCode
 };
-
-// DOTO: remove deprecated API.
-let deprecatedLinterInstance = null;
-
-Object.defineProperty(module.exports, "linter", {
-    enumerable: false,
-    get() {
-        if (!deprecatedLinterInstance) {
-            deprecatedLinterInstance = new Linter();
-        }
-
-        return deprecatedLinterInstance;
-    }
-});

lib/unsupported-api.js

@@ -0,0 +1,23 @@
+/**
+ * @fileoverview APIs that are not officially supported by ESLint.
+ *      These APIs may change or be removed at any time. Use at your
+ *      own risk.
+ * @author Nicholas C. Zakas
+ */
+
+"use strict";
+
+//-----------------------------------------------------------------------------
+// Requirements
+//-----------------------------------------------------------------------------
+
+const { FileEnumerator } = require("./cli-engine/file-enumerator");
+
+//-----------------------------------------------------------------------------
+// Exports
+//-----------------------------------------------------------------------------
+
+module.exports = {
+    builtinRules: require("./rules"),
+    FileEnumerator
+};

package.json

@@ -7,6 +7,11 @@
     "eslint": "./bin/eslint.js"
   },
   "main": "./lib/api.js",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": "./lib/api.js",
+    "./use-at-your-own-risk": "./lib/unsupported-api.js"
+  },
   "scripts": {
     "test": "node Makefile.js test",
     "test:cli": "mocha",

tests/lib/api.js

@@ -5,21 +5,33 @@
 
 "use strict";
 
+//-----------------------------------------------------------------------------
+// Requirements
+//-----------------------------------------------------------------------------
+
 const assert = require("chai").assert,
     api = require("../../lib/api");
 
+//-----------------------------------------------------------------------------
+// Tests
+//-----------------------------------------------------------------------------
+
 describe("api", () => {
 
     it("should have RuleTester exposed", () => {
         assert.isFunction(api.RuleTester);
     });
 
-    it("should have CLIEngine exposed", () => {
-        assert.isFunction(api.CLIEngine);
+    it("should not have CLIEngine exposed", () => {
+        assert.isUndefined(api.CLIEngine);
+    });
+
+    it("should not have linter exposed", () => {
+        assert.isUndefined(api.linter);
     });
 
-    it("should have linter exposed", () => {
-        assert.isObject(api.linter);
+    it("should have Linter exposed", () => {
+        assert.isFunction(api.Linter);
     });
 
     it("should have SourceCode exposed", () => {

tests/lib/unsupported-api.js

@@ -0,0 +1,30 @@
+/**
+ * @fileoverview Tests for unsupported-api.
+ * @author Nicholas C. Zakas
+ */
+
+"use strict";
+
+//-----------------------------------------------------------------------------
+// Requirements
+//-----------------------------------------------------------------------------
+
+const assert = require("chai").assert,
+    { LazyLoadingRuleMap } = require("../../lib/rules/utils/lazy-loading-rule-map"),
+    api = require("../../lib/unsupported-api");
+
+//-----------------------------------------------------------------------------
+// Tests
+//-----------------------------------------------------------------------------
+
+describe("unsupported-api", () => {
+
+    it("should have FileEnumerator exposed", () => {
+        assert.isFunction(api.FileEnumerator);
+    });
+
+    it("should have builtinRules exposed", () => {
+        assert.instanceOf(api.builtinRules, LazyLoadingRuleMap);
+    });
+
+});