feat: Use ESLINT_USE_FLAT_CONFIG environment variable for flat config (…

…#16356)

* feat: take flag config env into account

* test: take flag config env into account

* style: fix comments

* docs: document ESLINT_USE_FLAT_CONFIG

* fix: keep original process.env

* fix: ESLINT_USE_FLAT_CONFIG=true test

* fix: typo in docs

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

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

docs/src/user-guide/configuring/configuration-files-new.md

@@ -10,7 +10,7 @@ eleventyNavigation:
 ---
 
 ::: warning
-This is an experimental feature. To opt-in, place a `eslint.config.js` file in the root of your project. If you are using the API, you can use the configuration system described on this page by using the `FlatESLint` class, the `FlatRuleTester` class, or by setting `configType: "flat"` in the `Linter` class.
+This is an experimental feature. To opt-in, place a `eslint.config.js` file in the root of your project or set the `ESLINT_USE_FLAT_CONFIG` environment variable to `true`. To opt-out, even in the presence of a `eslint.config.js` file, set the environment variable to `false`. If you are using the API, you can use the configuration system described on this page by using the `FlatESLint` class, the `FlatRuleTester` class, or by setting `configType: "flat"` in the `Linter` class.
 :::
 
 ## Configuration File
@@ -585,10 +585,10 @@ Here, the `eslint:recommended` predefined configuration is applied first and the
 
 When ESLint is run on the command line, it first checks the current working directory for `eslint.config.js`, and if not found, will look to the next parent directory for the file. This search continues until either the file is found or the root directory is reached.
 
-You can prevent this search for `eslint.config.js` by using the `-c` or `--config--file` option on the command line to specify an alternate configuration file, such as:
+You can prevent this search for `eslint.config.js` by setting the `ESLINT_USE_FLAT_CONFIG` environment variable to `true` and using the `-c` or `--config` option on the command line to specify an alternate configuration file, such as:
 
 ```shell
-npx eslint -c some-other-file.js **/*.js
+ESLINT_USE_FLAT_CONFIG=true npx eslint -c some-other-file.js **/*.js
 ```
 
 In this case, ESLint will not search for `eslint.config.js` and will instead use `some-other-file.js`.

lib/cli.js

@@ -279,6 +279,31 @@ async function printResults(engine, results, format, outputFile, resultsMeta) {
     return true;
 }
 
+/**
+ * Returns whether flat config should be used.
+ * @param {boolean} [allowFlatConfig] Whether or not to allow flat config.
+ * @returns {Promise<boolean>} Where flat config should be used.
+ */
+async function shouldUseFlatConfig(allowFlatConfig) {
+    if (!allowFlatConfig) {
+        return false;
+    }
+
+    switch (process.env.ESLINT_USE_FLAT_CONFIG) {
+        case "true":
+            return true;
+        case "false":
+            return false;
+        default:
+
+            /*
+             * If neither explicitly enabled nor disabled, then use the presence
+             * of a flat config file to determine enablement.
+             */
+            return !!(await findFlatConfigFile(process.cwd()));
+    }
+}
+
 //------------------------------------------------------------------------------
 // Public Interface
 //------------------------------------------------------------------------------
@@ -308,7 +333,7 @@ const cli = {
          * switch to flat config we can remove this logic.
          */
 
-        const usingFlatConfig = allowFlatConfig && !!(await findFlatConfigFile(process.cwd()));
+        const usingFlatConfig = await shouldUseFlatConfig(allowFlatConfig);
 
         debug("Using flat config?", usingFlatConfig);
 

tests/lib/cli.js

@@ -137,6 +137,50 @@ describe("cli", () => {
 
         });
 
+        describe("flat config", () => {
+            const originalEnv = process.env;
+            const originalCwd = process.cwd;
+
+            beforeEach(() => {
+                process.env = { ...originalEnv };
+            });
+
+            afterEach(() => {
+                process.env = originalEnv;
+                process.cwd = originalCwd;
+            });
+
+            it(`should use it when an eslint.config.js is present and useFlatConfig is true:${configType}`, async () => {
+                process.cwd = getFixturePath;
+
+                const exitCode = await cli.execute(`--no-ignore --ext .js ${getFixturePath("files")}`, null, useFlatConfig);
+
+                // When flat config is used, we get an exit code of 2 because the --ext option is unrecognized.
+                assert.strictEqual(exitCode, useFlatConfig ? 2 : 0);
+            });
+
+            it(`should not use it when ESLINT_USE_FLAT_CONFIG=false even if an eslint.config.js is present:${configType}`, async () => {
+                process.env.ESLINT_USE_FLAT_CONFIG = "false";
+                process.cwd = getFixturePath;
+
+                const exitCode = await cli.execute(`--no-ignore --ext .js ${getFixturePath("files")}`, null, useFlatConfig);
+
+                assert.strictEqual(exitCode, 0);
+            });
+
+            it(`should use it when ESLINT_USE_FLAT_CONFIG=true and useFlatConfig is true even if an eslint.config.js is not present:${configType}`, async () => {
+                process.env.ESLINT_USE_FLAT_CONFIG = "true";
+
+                // Set the CWD to outside the fixtures/ directory so that no eslint.config.js is found
+                process.cwd = () => getFixturePath("..");
+
+                const exitCode = await cli.execute(`--no-ignore --ext .js ${getFixturePath("files")}`, null, useFlatConfig);
+
+                // When flat config is used, we get an exit code of 2 because the --ext option is unrecognized.
+                assert.strictEqual(exitCode, useFlatConfig ? 2 : 0);
+            });
+        });
+
         describe("when given a config with rules with options and severity level set to error", () => {
 
             const originalCwd = process.cwd;