Rename new `explain` subcommand to `rule`

We probably want to introduce multiple explain subcommands and
overloading `explain` to explain it all seems like a bad idea.
We may want to introduce a subcommand to explain config options and
config options may end up having the same name as their rules, e.g. the
current `banned-api` is both a rule name (although not yet exposed to
the user) and a config option.

The idea is:

* `ruff rule` lists all rules supported by ruff
* `ruff rule <code>` explains a specific rule
* `ruff linter` lists all linters supported by ruff
* `ruff linter <name>` lists all rules/options supported by a specific linter

(After this commit only the 2nd case is implemented.)

BREAKING_CHANGES.md

@@ -10,12 +10,12 @@
     ruff check .   # New! Also works.
 
     ruff --explain E402   # Still works.
-    ruff explain E402     # New! Also works. (And preferred.)
+    ruff rule E402        # New! Also works. (And preferred.)
 
     # Oops! The command has to come first.
     ruff --format json --explain E402   # No longer works.
     ruff --explain E402 --format json   # Works!
-    ruff explain E402   --format json   # Works! (And preferred.)
+    ruff rule E402   --format json      # Works! (And preferred.)
 
 This change is largely backwards compatible -- most users should experience
 no change in behavior. However, please note the following exceptions:
@@ -23,13 +23,13 @@ no change in behavior. However, please note the following exceptions:
 * Subcommands will now fail when invoked with unsupported arguments, instead
   of silently ignoring them. For example, the following will now fail:
 
-      ruff --explain E402 --respect-gitignore
+      ruff --clean --respect-gitignore
 
-  (the `explain` command doesn't support `--respect-gitignore`.)
+  (the `clean` command doesn't support `--respect-gitignore`.)
 
 * The semantics of `ruff <arg>` have changed slightly when `<arg>` is a valid subcommand.
-  For example, prior to this release, running `ruff explain` would run `ruff` over a file or
-  directory called `explain`. Now, `ruff explain` would invoke the `explain` subcommand.
+  For example, prior to this release, running `ruff rule` would run `ruff` over a file or
+  directory called `rule`. Now, `ruff rule` would invoke the `rule` subcommand.
 
 * Scripts that invoke ruff should supply `--` before any positional arguments.
   (The semantics of `ruff -- <arg>` have not changed.)

README.md

@@ -369,10 +369,10 @@ Ruff: An extremely fast Python linter.
 Usage: ruff [OPTIONS] <COMMAND>
 
 Commands:
-  check    Run Ruff on the given files or directories (default)
-  explain  Explain a rule
-  clean    Clear any caches in the current directory and any subdirectories
-  help     Print this message or the help of the given subcommand(s)
+  check  Run Ruff on the given files or directories (default)
+  rule   Explain a rule
+  clean  Clear any caches in the current directory and any subdirectories
+  help   Print this message or the help of the given subcommand(s)
 
 Options:
   -h, --help     Print help

ruff_cli/src/args.rs

@@ -33,7 +33,7 @@ pub enum Command {
     Check(CheckArgs),
     /// Explain a rule.
     #[clap(alias = "--explain")]
-    Explain {
+    Rule {
         #[arg(value_parser=Rule::from_code)]
         rule: &'static Rule,
 

ruff_cli/src/commands.rs

@@ -268,7 +268,7 @@ struct Explanation<'a> {
 }
 
 /// Explain a `Rule` to the user.
-pub fn explain(rule: &Rule, format: HelpFormat) -> Result<()> {
+pub fn rule(rule: &Rule, format: HelpFormat) -> Result<()> {
     let (linter, _) = Linter::parse_code(rule.code()).unwrap();
     match format {
         HelpFormat::Text => {

ruff_cli/src/main.rs

@@ -77,7 +77,7 @@ quoting the executed command, along with the relevant file contents and `pyproje
     set_up_logging(&log_level)?;
 
     match command {
-        Command::Explain { rule, format } => commands::explain(rule, format)?,
+        Command::Rule { rule, format } => commands::rule(rule, format)?,
         Command::Clean => commands::clean(log_level)?,
         Command::GenerateShellCompletion { shell } => {
             shell.generate(&mut Args::command(), &mut io::stdout());
@@ -272,7 +272,7 @@ fn check(args: CheckArgs, log_level: LogLevel) -> Result<ExitCode> {
 
 fn rewrite_legacy_subcommand(cmd: &str) -> &str {
     match cmd {
-        "--explain" => "explain",
+        "--explain" => "rule",
         "--clean" => "clean",
         "--generate-shell-completion" => "generate-shell-completion",
         cmd => cmd,