feat: allow flat config files to export a Promise (#17301)

* feat: allow flat config files to export a Promise

Fixes #16864, #16580

* Update docs/src/use/configure/configuration-files-new.md

Co-authored-by: Nicholas C. Zakas <nicholas@humanwhocodes.com>

* Update docs/src/use/configure/configuration-files-new.md

Co-authored-by: Nicholas C. Zakas <nicholas@humanwhocodes.com>

---------

Co-authored-by: Nicholas C. Zakas <nicholas@humanwhocodes.com>

docs/src/use/configure/configuration-files-new.md

@@ -26,11 +26,38 @@ export default [
             "prefer-const": "error"
         }
     }
-]
+];
 ```
 
 In this example, the configuration array contains just one configuration object. The configuration object enables two rules: `semi` and `prefer-const`. These rules are applied to all of the files ESLint processes using this config file.
 
+If your project does not specify `"type":"module"` in its `package.json` file, then `eslint.config.js` must be in CommonJS format, such as:
+
+```js
+module.exports = [
+    {
+        rules: {
+            semi: "error",
+            "prefer-const": "error"
+        }
+    }
+];
+```
+
+The configuration file can also export a promise that resolves to the configuration array. This can be useful for using ESM dependencies in CommonJS configuration files, as in this example:
+
+```js
+module.exports = (async () => {
+
+    const someDependency = await import("some-esm-dependency");
+
+    return [
+        // ... use `someDependency` here
+    ];
+
+})();
+```
+
 ## Configuration Objects
 
 Each configuration object contains all of the information ESLint needs to execute on a set of files. Each configuration object is made up of these properties:

tests/fixtures/promise-config/a.js

@@ -0,0 +1 @@
+var foo = "bar";

tests/fixtures/promise-config/eslint.config.js

@@ -0,0 +1,5 @@
+module.exports = Promise.resolve([{
+    rules: {
+        quotes: ["error", "single"]
+    }
+}]);

tests/lib/eslint/flat-eslint.js

@@ -761,6 +761,18 @@ describe("FlatESLint", () => {
             eslint = new FlatESLint();
             await assert.rejects(() => eslint.lintText("var a = 0", { warnIgnored: "" }), /'options.warnIgnored' must be a boolean or undefined/u);
         });
+
+        it("should work with config file that exports a promise", async () => {
+            eslint = new FlatESLint({
+                cwd: getFixturePath("promise-config")
+            });
+            const results = await eslint.lintText('var foo = "bar";');
+
+            assert.strictEqual(results.length, 1);
+            assert.strictEqual(results[0].messages.length, 1);
+            assert.strictEqual(results[0].messages[0].severity, 2);
+            assert.strictEqual(results[0].messages[0].ruleId, "quotes");
+        });
     });
 
     describe("lintFiles()", () => {
@@ -991,6 +1003,19 @@ describe("FlatESLint", () => {
             assert.strictEqual(results[0].suppressedMessages.length, 0);
         });
 
+        it("should work with config file that exports a promise", async () => {
+            eslint = new FlatESLint({
+                cwd: getFixturePath("promise-config")
+            });
+            const results = await eslint.lintFiles(["a*.js"]);
+
+            assert.strictEqual(results.length, 1);
+            assert.strictEqual(results[0].filePath, getFixturePath("promise-config", "a.js"));
+            assert.strictEqual(results[0].messages.length, 1);
+            assert.strictEqual(results[0].messages[0].severity, 2);
+            assert.strictEqual(results[0].messages[0].ruleId, "quotes");
+        });
+
         // https://github.com/eslint/eslint/issues/16265
         describe("Dot files in searches", () => {