feat: Add --inspect-config CLI flag (#18270)

* feat: Add --inspect-config CLI flag

fixes #18255

* Update docs to indicate only flat config mode is supported

* Update tests/lib/options.js

Co-authored-by: Francesco Trotta <github@fasttime.org>

---------

Co-authored-by: Francesco Trotta <github@fasttime.org>

bin/eslint.js

@@ -148,6 +148,18 @@ ${getErrorMessage(error)}`;
         return;
     }
 
+    // Call the config inspector if `--inspect-config` is present.
+    if (process.argv.includes("--inspect-config")) {
+
+        console.warn("You can also run this command directly using 'npx @eslint/config-inspector' in the same directory as your configuration file.");
+
+        const spawn = require("cross-spawn");
+
+        spawn.sync("npx", ["@eslint/config-inspector"], { encoding: "utf8", stdio: "inherit" });
+
+        return;
+    }
+
     // Otherwise, call the CLI.
     const cli = require("../lib/cli");
     const exitCode = await cli.execute(

docs/src/use/command-line-interface.md

@@ -67,36 +67,33 @@ You can view all the CLI options by running `npx eslint -h`.
 eslint [options] file.js [file.js] [dir]
 
 Basic configuration:
-  --no-eslintrc                   Disable use of configuration from .eslintrc.*
-  -c, --config path::String       Use this configuration, overriding .eslintrc.* config options if present
-  --env [String]                  Specify environments
-  --ext [String]                  Specify JavaScript file extensions
+  --no-config-lookup              Disable look up for eslint.config.js
+  -c, --config path::String       Use this configuration instead of eslint.config.js, eslint.config.mjs, or
+                                  eslint.config.cjs
+  --inspect-config                Open the config inspector with the current configuration
   --global [String]               Define global variables
   --parser String                 Specify the parser to be used
   --parser-options Object         Specify parser options
-  --resolve-plugins-relative-to path::String  A folder where plugins should be resolved from, CWD by default
 
-Specify rules and plugins:
+Specify Rules and Plugins:
   --plugin [String]               Specify plugins
   --rule Object                   Specify rules
-  --rulesdir [path::String]       Load additional rules from this directory. Deprecated: Use rules from plugins
 
-Fix problems:
+Fix Problems:
   --fix                           Automatically fix problems
   --fix-dry-run                   Automatically fix problems without saving the changes to the file system
   --fix-type Array                Specify the types of fixes to apply (directive, problem, suggestion, layout)
 
-Ignore files:
-  --ignore-path path::String      Specify path of ignore file
+Ignore Files:
   --no-ignore                     Disable use of ignore files and patterns
   --ignore-pattern [String]       Pattern of files to ignore (in addition to those in .eslintignore)
 
 Use stdin:
   --stdin                         Lint code provided on <STDIN> - default: false
   --stdin-filename String         Specify filename to process STDIN as
 
-Handle warnings:
-  --quiet                         Report and check errors only - default: false
+Handle Warnings:
+  --quiet                         Report errors only - default: false
   --max-warnings Int              Number of warnings to trigger nonzero exit code - default: -1
 
 Output:
@@ -107,20 +104,22 @@ Output:
 Inline configuration comments:
   --no-inline-config              Prevent comments from changing config or rules
   --report-unused-disable-directives  Adds reported errors for unused eslint-disable and eslint-enable directives
-  --report-unused-disable-directives-severity String  Chooses severity level for reporting unused eslint-disable and eslint-enable directives - either: off, warn, error, 0, 1, or 2
+  --report-unused-disable-directives-severity String  Chooses severity level for reporting unused eslint-disable and
+                                                      eslint-enable directives - either: off, warn, error, 0, 1, or 2
 
 Caching:
   --cache                         Only check changed files - default: false
   --cache-file path::String       Path to the cache file. Deprecated: use --cache-location - default: .eslintcache
   --cache-location path::String   Path to the cache file or directory
-  --cache-strategy String         Strategy to use for detecting changed files in the cache - either: metadata or content - default: metadata
+  --cache-strategy String         Strategy to use for detecting changed files in the cache - either: metadata or
+                                  content - default: metadata
 
 Miscellaneous:
   --init                          Run config initialization wizard - default: false
   --env-info                      Output execution environment information - default: false
   --no-error-on-unmatched-pattern  Prevent errors when pattern is unmatched
   --exit-on-fatal-error           Exit with exit code 2 in case of fatal error - default: false
-  --no-warn-ignored               Suppress warnings when the file list includes ignored files. *Flat Config Mode Only*
+  --no-warn-ignored               Suppress warnings when the file list includes ignored files
   --pass-on-no-patterns           Exit with exit code 0 in case no file patterns are passed
   --debug                         Output debugging information
   -h, --help                      Show help
@@ -160,6 +159,18 @@ This example uses the configuration file at `~/my-eslint.json`.
 
 If `.eslintrc.*` and/or `package.json` files are also used for configuration (i.e., `--no-eslintrc` was not specified), the configurations are merged. Options from this configuration file have precedence over the options from `.eslintrc.*` and `package.json` files.
 
+#### `--inspect-config`
+
+**Flat Config Mode Only.** This option runs `npx @eslint/config-inspector` to start the config inspector. You can use the config inspector to better understand what your configuration is doing and which files it applies to. When you use this flag, the CLI does not perform linting.
+
+* **Argument Type**: No argument.
+
+##### `--inspect-config` example
+
+```shell
+npx eslint --inspect-config
+```
+
 #### `--env`
 
 **eslintrc Mode Only.** This option enables specific environments.

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

@@ -157,6 +157,10 @@ export default [
 
 This configuration object applies to all files except those ending with `.config.js`. Effectively, this is like having `files` set to `**/*`. In general, it's a good idea to always include `files` if you are specifying `ignores`.
 
+::: tip
+Use the [config inspector](https://github.com/eslint/config-inspector) (`--inspect-config` in the CLI) to test which config objects apply to a specific file.
+:::
+
 #### Globally ignoring files with `ignores`
 
 If `ignores` is used without any other keys in the configuration object, then the patterns act as global ignores. Here's an example:

lib/options.js

@@ -104,6 +104,16 @@ module.exports = function(usingFlatConfig) {
         };
     }
 
+    let inspectConfigFlag;
+
+    if (usingFlatConfig) {
+        inspectConfigFlag = {
+            option: "inspect-config",
+            type: "Boolean",
+            description: "Open the config inspector with the current configuration"
+        };
+    }
+
     let extFlag;
 
     if (!usingFlatConfig) {
@@ -185,6 +195,7 @@ module.exports = function(usingFlatConfig) {
                     ? "Use this configuration instead of eslint.config.js, eslint.config.mjs, or eslint.config.cjs"
                     : "Use this configuration, overriding .eslintrc.* config options if present"
             },
+            inspectConfigFlag,
             envFlag,
             extFlag,
             {

tests/lib/options.js

@@ -445,4 +445,12 @@ describe("options", () => {
         });
     });
 
+    describe("--inspect-config", () => {
+        it("should return true when --inspect-config is passed", () => {
+            const currentOptions = flatOptions.parse("--inspect-config");
+
+            assert.isTrue(currentOptions.inspectConfig);
+        });
+    });
+
 });