feat!: remove v10_* and inactive unstable_* flags (#20225)

sethamus · web-flow · commit 4f880ee02992 · 2025-11-07T16:19:22.000+01:00
* fix!: remove `v10_*` and inactive `unstable_*` flags

* format

* remove `LegacyConfigLoader`

* fix ci

* revert removal of CLI test

* Merge branch 'main' into remove-v10-config-flags

* update the migration guide

* update v10 migration guide

* revert formatting change

* show just one form of the CLI option to avoid confusion
diff --git a/.trunk/trunk.yaml b/.trunk/trunk.yaml
@@ -64,6 +64,10 @@ lint:
         - linters: [markdownlint]
           paths:
               - CHANGELOG.md
+        - linters: [eslint]
+          paths:
+              - tests/fixtures/**
+              - docs/_examples/**
 actions:
     disabled:
         - trunk-announce
diff --git a/docs/src/use/configure/configuration-files.md b/docs/src/use/configure/configuration-files.md
@@ -780,32 +780,16 @@ export default {
 
 ## Configuration File Resolution
 
-When ESLint is run on the command line, it first checks the current working directory for `eslint.config.js`. If that file is found, then the search stops, otherwise it checks for `eslint.config.mjs`. If that file is found, then the search stops, otherwise it checks for `eslint.config.cjs`. If none of the files are found, it checks the parent directory for each file. This search continues until either a config file is found or the root directory is reached.
+When ESLint is run on the command line, it determines configuration for each target file by first looking in the directory that contains the file and then searching up ancestor directories until it finds an `eslint.config.*` file. This behavior improves support for monorepos, where subdirectories can have their own configuration files.
 
-You can prevent this search for `eslint.config.js` by using the `-c` or `--config` option on the command line to specify an alternate configuration file, such as:
+You can prevent this search by using the `-c` or `--config` option on the command line to specify an alternate configuration file, such as:
 
 {{ npx_tabs({
     package: "eslint",
     args: ["--config", "some-other-file.js", "**/*.js"]
 }) }}
 
-In this case, ESLint does not search for `eslint.config.js` and instead uses `some-other-file.js`.
-
-### Experimental Configuration File Resolution
-
-::: warning
-This feature is experimental and its details may change before being finalized. This behavior will be the new lookup behavior starting in v10.0.0, but you can try it today using a feature flag.
-:::
-
-You can use the `v10_config_lookup_from_file` flag to change the way ESLint searches for configuration files. Instead of searching from the current working directory, ESLint will search for a configuration file by first starting in the directory of the file being linted and then searching up its ancestor directories until it finds a `eslint.config.js` file (or any other extension of configuration file). This behavior is better for monorepos, where each subdirectory may have its own configuration file.
-
-To use this feature on the command line, use the `--flag` flag:
-
-```shell
-npx eslint --flag v10_config_lookup_from_file .
-```
-
-For more information about using feature flags, see [Feature Flags](../../flags/).
+In this case, ESLint does not search for configuration files and instead uses `some-other-file.js`.
 
 ## TypeScript Configuration Files
 
diff --git a/docs/src/use/migrate-to-10.0.0.md b/docs/src/use/migrate-to-10.0.0.md
@@ -16,6 +16,7 @@ The lists below are ordered roughly by the number of users each change is expect
 ### Breaking changes for users
 
 - [Node.js < v20.19, v21, v23 are no longer supported](#drop-old-node)
+- [New configuration file lookup algorithm](#config-lookup-from-file)
 - [`no-shadow-restricted-names` now reports `globalThis` by default](#no-shadow-restricted-names)
 
 ### Breaking changes for plugin developers
@@ -25,6 +26,7 @@ The lists below are ordered roughly by the number of users each change is expect
 ### Breaking changes for integration developers
 
 - [Node.js < v20.19, v21, v23 are no longer supported](#drop-old-node)
+- [New configuration file lookup algorithm](#config-lookup-from-file)
 
 ---
 
@@ -40,6 +42,20 @@ ESLint is officially dropping support for these versions of Node.js starting wit
 
 **Related issue(s):** [#19969](https://github.com/eslint/eslint/issues/19969)
 
+## <a name="config-lookup-from-file"></a> New configuration file lookup algorithm
+
+In ESLint v9, the alternate config lookup behavior could be enabled with the `v10_config_lookup_from_file` feature flag. This behavior made ESLint locate `eslint.config.*` by starting from the directory of each linted file and searching up towards the filesystem root. In ESLint v10, this behavior is now the default and the `v10_config_lookup_from_file` flag has been removed. Attempting to use this flag will now result in an error.
+
+**To address:**
+
+- Remove any usage of the flag in your setup:
+    - CLI: remove `--flag v10_config_lookup_from_file`.
+    - Environment: remove `v10_config_lookup_from_file` from `ESLINT_FLAGS`.
+    - API: remove `"v10_config_lookup_from_file"` from the `flags` array passed to `new ESLint()` or `new Linter()`.
+- If you relied on the previous (cwd-based) lookup behavior, provide an explicit config path with `--config path/to/eslint.config.js`.
+
+**Related issue(s):** [#19967](https://github.com/eslint/eslint/issues/19967)
+
 ## <a name="no-shadow-restricted-names"></a> `no-shadow-restricted-names` now reports `globalThis` by default
 
 In ESLint v10, the [`no-shadow-restricted-names`](../rules/no-shadow-restricted-names) rule now treats `globalThis` as a restricted name by default. Consequently, the `reportGlobalThis` option now defaults to `true` (previously `false`). As a result, declarations such as `const globalThis = "foo";` or `function globalThis() {}` will now be reported by default.
diff --git a/lib/config/config-loader.js b/lib/config/config-loader.js
@@ -666,151 +666,4 @@ class ConfigLoader {
 	}
 }
 
-/**
- * Encapsulates the loading and caching of configuration files when looking up
- * from the current working directory.
- */
-class LegacyConfigLoader extends ConfigLoader {
-	/**
-	 * The options to use when loading configuration files.
-	 * @type {ConfigLoaderOptions}
-	 */
-	#options;
-
-	/**
-	 * The cached config file path for this instance.
-	 * @type {Promise<{configFilePath:string,basePath:string}|undefined>}
-	 */
-	#configFilePath;
-
-	/**
-	 * The cached config array for this instance.
-	 * @type {FlatConfigArray|Promise<FlatConfigArray>}
-	 */
-	#configArray;
-
-	/**
-	 * Creates a new instance.
-	 * @param {ConfigLoaderOptions} options The options to use when loading configuration files.
-	 */
-	constructor(options) {
-		const normalizedOptions = options.warningService
-			? options
-			: { ...options, warningService: new WarningService() };
-		super(normalizedOptions);
-		this.#options = normalizedOptions;
-	}
-
-	/**
-	 * Determines which config file to use. This is determined by seeing if an
-	 * override config file was specified, and if so, using it; otherwise, as long
-	 * as override config file is not explicitly set to `false`, it will search
-	 * upwards from the cwd for a file named `eslint.config.js`.
-	 * @returns {Promise<{configFilePath:string|undefined,basePath:string}>} Location information for
-	 *      the config file.
-	 */
-	#locateConfigFileToUse() {
-		if (!this.#configFilePath) {
-			this.#configFilePath = ConfigLoader.locateConfigFileToUse({
-				useConfigFile: this.#options.configFile,
-				cwd: this.#options.cwd,
-			});
-		}
-
-		return this.#configFilePath;
-	}
-
-	/**
-	 * Calculates the config array for this run based on inputs.
-	 * @param {string} configFilePath The absolute path to the config file to use if not overridden.
-	 * @param {string} basePath The base path to use for relative paths in the config file.
-	 * @returns {Promise<FlatConfigArray>} The config array for `eslint`.
-	 */
-	async #calculateConfigArray(configFilePath, basePath) {
-		// check for cached version first
-		if (this.#configArray) {
-			return this.#configArray;
-		}
-
-		// ensure `ConfigLoader.calculateConfigArray` is called only once
-		this.#configArray = ConfigLoader.calculateConfigArray(
-			configFilePath,
-			basePath,
-			this.#options,
-		);
-
-		// Unwrap the promise. This is primarily for the sync `getCachedConfigArrayForPath` method.
-		this.#configArray = await this.#configArray;
-
-		return this.#configArray;
-	}
-
-	/**
-	 * Returns the config file path for the given directory. This will either use
-	 * the override config file that was specified in the constructor options or
-	 * search for a config file from the directory of the file being linted.
-	 * @param {string} dirPath The directory path to get the config file path for.
-	 * @returns {Promise<string|undefined>} The config file path or `undefined` if not found.
-	 * @throws {Error} If `fileOrDirPath` is not a non-empty string.
-	 * @throws {Error} If `fileOrDirPath` is not an absolute path.
-	 */
-	async findConfigFileForPath(dirPath) {
-		assertValidFilePath(dirPath);
-
-		const { configFilePath } = await this.#locateConfigFileToUse();
-
-		return configFilePath;
-	}
-
-	/**
-	 * Returns a configuration object for the given file based on the CLI options.
-	 * This is the same logic used by the ESLint CLI executable to determine
-	 * configuration for each file it processes.
-	 * @param {string} dirPath The path of the directory to retrieve config for.
-	 * @returns {Promise<FlatConfigArray>} A configuration object for the file.
-	 */
-	async loadConfigArrayForDirectory(dirPath) {
-		assertValidFilePath(dirPath);
-
-		debug(`[Legacy]: Calculating config for ${dirPath}`);
-
-		const { configFilePath, basePath } =
-			await this.#locateConfigFileToUse();
-
-		debug(
-			`[Legacy]: Using config file ${configFilePath} and base path ${basePath}`,
-		);
-		return this.#calculateConfigArray(configFilePath, basePath);
-	}
-
-	/**
-	 * Returns a configuration array for the given directory based on the CLI options.
-	 * This is a synchronous operation and does not read any files from disk. It's
-	 * intended to be used in locations where we know the config file has already
-	 * been loaded and we just need to get the configuration for a file.
-	 * @param {string} dirPath The path of the directory to retrieve a config object for.
-	 * @returns {FlatConfigArray} A configuration object for the file.
-	 * @throws {Error} If `dirPath` is not a non-empty string.
-	 * @throws {Error} If `dirPath` is not an absolute path.
-	 * @throws {Error} If the config file was not already loaded.
-	 */
-	getCachedConfigArrayForPath(dirPath) {
-		assertValidFilePath(dirPath);
-
-		debug(`[Legacy]: Looking up cached config for ${dirPath}`);
-
-		if (!this.#configArray) {
-			throw new Error(`Could not find config file for ${dirPath}`);
-		}
-
-		if (typeof this.#configArray.then === "function") {
-			throw new Error(
-				`Config array for ${dirPath} has not yet been calculated or an error occurred during the calculation`,
-			);
-		}
-
-		return this.#configArray;
-	}
-}
-
-module.exports = { ConfigLoader, LegacyConfigLoader };
+module.exports = { ConfigLoader };
diff --git a/lib/eslint/eslint-helpers.js b/lib/eslint/eslint-helpers.js
@@ -20,7 +20,7 @@ const globParent = require("glob-parent");
 const { Linter } = require("../linter");
 const { getShorthandName } = require("../shared/naming");
 const LintResultCache = require("../cli-engine/lint-result-cache");
-const { ConfigLoader, LegacyConfigLoader } = require("../config/config-loader");
+const { ConfigLoader } = require("../config/config-loader");
 const createDebug = require("debug");
 
 //-----------------------------------------------------------------------------
@@ -247,7 +247,7 @@ async function globMatch({ basePath, pattern }) {
  *      to match.
  * @param {Array<string>} options.rawPatterns An array of glob patterns
  *      as the user inputted them. Used for errors.
- * @param {ConfigLoader|LegacyConfigLoader} options.configLoader The config array to use for
+ * @param {ConfigLoader} options.configLoader The config array to use for
  *      determining what to ignore.
  * @param {boolean} options.errorOnUnmatchedPattern Determines if an error
  *      should be thrown when a pattern is unmatched.
@@ -425,7 +425,7 @@ async function throwErrorForUnmatchedPatterns({
  * @param {Object} options The options for this function.
  * @param {Map<string,GlobSearch>} options.searches
  *      A map of absolute path glob patterns to match.
- * @param {ConfigLoader|LegacyConfigLoader} options.configLoader The config loader to use for
+ * @param {ConfigLoader} options.configLoader The config loader to use for
  *      determining what to ignore.
  * @param {boolean} options.errorOnUnmatchedPattern Determines if an
  *      unmatched glob pattern should throw an error.
@@ -506,7 +506,7 @@ async function globMultiSearch({
  * @param {boolean} args.globInputPaths true to interpret glob patterns,
  *      false to not interpret glob patterns.
  * @param {string} args.cwd The current working directory to find from.
- * @param {ConfigLoader|LegacyConfigLoader} args.configLoader The config loader for the current run.
+ * @param {ConfigLoader} args.configLoader The config loader for the current run.
  * @param {boolean} args.errorOnUnmatchedPattern Determines if an unmatched pattern
  *      should throw an error.
  * @returns {Promise<Array<string>>} The fully resolved file paths.
@@ -1428,9 +1428,7 @@ function createConfigLoader(
 		warningService,
 	};
 
-	return linter.hasFlag("v10_config_lookup_from_file")
-		? new ConfigLoader(configLoaderOptions)
-		: new LegacyConfigLoader(configLoaderOptions);
+	return new ConfigLoader(configLoaderOptions);
 }
 
 //-----------------------------------------------------------------------------
diff --git a/lib/shared/flags.js b/lib/shared/flags.js
@@ -28,10 +28,6 @@
 const activeFlags = new Map([
 	["test_only", "Used only for testing."],
 	["test_only_2", "Used only for testing."],
-	[
-		"v10_config_lookup_from_file",
-		"Look up `eslint.config.js` from the file being linted.",
-	],
 	[
 		"unstable_native_nodejs_ts_config",
 		"Use native Node.js to load TypeScript configuration.",
@@ -66,21 +62,6 @@ const inactiveFlags = new Map([
 				"Used only for testing flags whose features have been abandoned.",
 		},
 	],
-	[
-		"unstable_ts_config",
-		{
-			description: "Enable TypeScript configuration files.",
-			replacedBy: null,
-		},
-	],
-	[
-		"unstable_config_lookup_from_file",
-		{
-			description:
-				"Look up `eslint.config.js` from the file being linted.",
-			replacedBy: "v10_config_lookup_from_file",
-		},
-	],
 ]);
 
 /**
diff --git a/tests/lib/cli.js b/tests/lib/cli.js
@@ -3212,14 +3212,12 @@ describe("cli", () => {
 				});
 			});
 
-			describe("v10_config_lookup_from_file", () => {
-				const flag = "v10_config_lookup_from_file";
-
+			describe("config lookup from file", () => {
 				it("should throw an error when text is passed and no config file is found", async () => {
 					await stdAssert.rejects(
 						() =>
 							cli.execute(
-								`--flag ${flag} --stdin --stdin-filename /foo.js"`,
+								'--stdin --stdin-filename /foo.js"',
 								"var foo = 'bar';",
 								true,
 							),
diff --git a/tests/lib/config/config-loader.js b/tests/lib/config/config-loader.js
diff --git a/tests/lib/eslint/eslint.js b/tests/lib/eslint/eslint.js
