refactor: mark ESLint.findConfigFile() as async, add missing docs (#20157)

Pixel998 · web-flow · commit e1ac05e2fae7 · 2025-09-25T16:28:58.000+08:00
docs: add missing docs for `ESLint.findConfigFile()`
diff --git a/docs/src/integrate/nodejs-api.md b/docs/src/integrate/nodejs-api.md
@@ -259,6 +259,24 @@ This method calculates the configuration for a given file, which can be useful f
 - (`Promise<Object>`)<br>
   The promise that will be fulfilled with a configuration object.
 
+### ◆ eslint.findConfigFile(filePath)
+
+```js
+const configFilePath = await eslint.findConfigFile(filePath);
+```
+
+This method finds the configuration file that this `ESLint` instance would use based on the options passed to the constructor.
+
+#### Parameters
+
+- `filePath` (`string`)<br>
+  Optional. The path of a file for which to find the associated config file. If omitted, ESLint determines the config file based on the current working directory of this instance.
+
+#### Return Value
+
+- (`Promise<string | undefined>`)<br>
+  The promise that will be fulfilled with the absolute path to the config file being used, or `undefined` when no config file is used (for example, when `overrideConfigFile: true` is set).
+
 ### ◆ eslint.isPathIgnored(filePath)
 
 ```js
diff --git a/lib/eslint/eslint.js b/lib/eslint/eslint.js
@@ -1299,7 +1299,7 @@ class ESLint {
 	 * @returns {Promise<string|undefined>} The path to the config file being used or
 	 *      `undefined` if no config file is being used.
 	 */
-	findConfigFile(filePath) {
+	async findConfigFile(filePath) {
 		const options = privateMembers.get(this).options;
 
 		/*
diff --git a/tests/lib/eslint/eslint.js b/tests/lib/eslint/eslint.js
@@ -10862,6 +10862,60 @@ describe("ESLint", () => {
 					configFilePath,
 				);
 			});
+
+			it("should return undefined when overrideConfigFile is true even when filePath is provided", async () => {
+				const engine = new ESLint({
+					flags,
+					overrideConfigFile: true,
+					cwd: getFixturePath("lookup-from-file"),
+				});
+
+				const filePath = path.join("subdir", "code.js");
+				assert.strictEqual(
+					await engine.findConfigFile(filePath),
+					void 0,
+				);
+			});
+
+			it("should return custom config file path when overrideConfigFile is a nonempty string even when filePath is provided", async () => {
+				const engine = new ESLint({
+					flags,
+					overrideConfigFile: "my-config.js",
+				});
+
+				const configFilePath = path.resolve(
+					__dirname,
+					"../../../my-config.js",
+				);
+
+				assert.strictEqual(
+					await engine.findConfigFile("some/file.js"),
+					configFilePath,
+				);
+			});
+
+			it("should return the config file relative to the provided filePath when specified", async () => {
+				const engine = new ESLint({
+					flags,
+					cwd: getFixturePath("lookup-from-file"),
+				});
+
+				const foundConfig = await engine.findConfigFile(
+					path.join("subdir", "code.js"),
+				);
+
+				const expectedConfig = flags.includes(
+					"v10_config_lookup_from_file",
+				)
+					? getFixturePath(
+							"lookup-from-file",
+							"subdir",
+							"eslint.config.js",
+						)
+					: getFixturePath("lookup-from-file", "eslint.config.js");
+
+				assert.strictEqual(foundConfig, expectedConfig);
+			});
 		});
 
 		describe("Use stats option", () => {
