Add cargo dev generate-all --check and catch outdated docs in cargo test (#3320)

crates/ruff_dev/src/generate_all.rs

@@ -4,22 +4,32 @@ use anyhow::Result;
 
 use crate::{generate_cli_help, generate_docs, generate_json_schema};
 
+pub const REGENERATE_ALL_COMMAND: &str = "cargo dev generate-all";
+
 #[derive(clap::Args)]
 pub struct Args {
     /// Write the generated artifacts to stdout (rather than to the filesystem).
     #[arg(long)]
     dry_run: bool,
+    /// Don't write to the file, check if the file is up-to-date and error if not
+    #[arg(long)]
+    check: bool,
 }
 
 pub fn main(args: &Args) -> Result<()> {
-    generate_docs::main(&generate_docs::Args {
-        dry_run: args.dry_run,
-    })?;
+    // Not checked in
+    if !args.check {
+        generate_docs::main(&generate_docs::Args {
+            dry_run: args.dry_run,
+        })?;
+    }
     generate_json_schema::main(&generate_json_schema::Args {
         dry_run: args.dry_run,
+        check: args.check,
     })?;
     generate_cli_help::main(&generate_cli_help::Args {
         dry_run: args.dry_run,
+        check: args.check,
     })?;
     Ok(())
 }

crates/ruff_dev/src/generate_cli_help.rs

@@ -1,13 +1,13 @@
 //! Generate CLI help.
 #![allow(clippy::print_stdout, clippy::print_stderr)]
 
-use std::fs::OpenOptions;
-use std::io::Write;
 use std::path::PathBuf;
 use std::{fs, str};
 
-use anyhow::Result;
+use anyhow::{bail, Result};
+use pretty_assertions::StrComparison;
 
+use crate::generate_all::REGENERATE_ALL_COMMAND;
 use crate::ROOT_DIR;
 
 const COMMAND_HELP_BEGIN_PRAGMA: &str = "<!-- Begin auto-generated command help. -->\n";
@@ -21,17 +21,22 @@ pub struct Args {
     /// Write the generated help to stdout (rather than to `docs/configuration.md`).
     #[arg(long)]
     pub(crate) dry_run: bool,
+    /// Don't write to the file, check if the file is up-to-date and error if not
+    #[arg(long)]
+    pub(crate) check: bool,
 }
 
 fn trim_lines(s: &str) -> String {
     s.lines().map(str::trim_end).collect::<Vec<_>>().join("\n")
 }
 
-fn replace_docs_section(content: &str, begin_pragma: &str, end_pragma: &str) -> Result<()> {
-    // Read the existing file.
-    let file = PathBuf::from(ROOT_DIR).join("docs/configuration.md");
-    let existing = fs::read_to_string(&file)?;
-
+/// Takes the existing file contents, inserts the section, returns the transformed content
+fn replace_docs_section(
+    existing: &str,
+    section: &str,
+    begin_pragma: &str,
+    end_pragma: &str,
+) -> String {
     // Extract the prefix.
     let index = existing
         .find(begin_pragma)
@@ -44,13 +49,7 @@ fn replace_docs_section(content: &str, begin_pragma: &str, end_pragma: &str) ->
         .expect("Unable to find end pragma");
     let suffix = &existing[index..];
 
-    // Write the prefix, new contents, and suffix.
-    let mut f = OpenOptions::new().write(true).truncate(true).open(&file)?;
-    writeln!(f, "{prefix}")?;
-    write!(f, "{content}")?;
-    write!(f, "{suffix}")?;
-
-    Ok(())
+    format!("{prefix}\n{section}{suffix}")
 }
 
 pub fn main(args: &Args) -> Result<()> {
@@ -64,17 +63,49 @@ pub fn main(args: &Args) -> Result<()> {
         print!("{command_help}");
         print!("{subcommand_help}");
     } else {
-        replace_docs_section(
+        // Read the existing file.
+        let filename = "docs/configuration.md";
+        let file = PathBuf::from(ROOT_DIR).join(filename);
+        let existing = fs::read_to_string(&file)?;
+
+        let new = replace_docs_section(
+            &existing,
             &format!("```text\n{command_help}\n```\n\n"),
             COMMAND_HELP_BEGIN_PRAGMA,
             COMMAND_HELP_END_PRAGMA,
-        )?;
-        replace_docs_section(
+        );
+        let new = replace_docs_section(
+            &new,
             &format!("```text\n{subcommand_help}\n```\n\n"),
             SUBCOMMAND_HELP_BEGIN_PRAGMA,
             SUBCOMMAND_HELP_END_PRAGMA,
-        )?;
+        );
+
+        if args.check {
+            if existing == new {
+                println!("up-to-date: {filename}");
+            } else {
+                let comparison = StrComparison::new(&existing, &new);
+                bail!("{filename} changed, please run `{REGENERATE_ALL_COMMAND}`:\n{comparison}");
+            }
+        } else {
+            fs::write(file, &new)?;
+        }
     }
 
     Ok(())
 }
+
+#[cfg(test)]
+mod test {
+    use super::{main, Args};
+    use anyhow::Result;
+
+    #[test]
+    fn test_generate_json_schema() -> Result<()> {
+        main(&Args {
+            dry_run: false,
+            check: true,
+        })
+    }
+}

crates/ruff_dev/src/generate_docs.rs

@@ -2,14 +2,18 @@
 #![allow(clippy::print_stdout, clippy::print_stderr)]
 
 use std::fs;
+use std::path::PathBuf;
 
 use anyhow::Result;
 use regex::{Captures, Regex};
+use strum::IntoEnumIterator;
+
 use ruff::registry::{Linter, Rule, RuleNamespace};
 use ruff::settings::options::Options;
 use ruff::settings::options_base::ConfigurationOptions;
 use ruff::AutofixAvailability;
-use strum::IntoEnumIterator;
+
+use crate::ROOT_DIR;
 
 #[derive(clap::Args)]
 pub struct Args {
@@ -44,11 +48,17 @@ pub fn main(args: &Args) -> Result<()> {
 
             process_documentation(explanation.trim(), &mut output);
 
+            let filename = PathBuf::from(ROOT_DIR)
+                .join("docs")
+                .join("rules")
+                .join(rule.as_ref())
+                .with_extension("md");
+
             if args.dry_run {
                 println!("{output}");
             } else {
                 fs::create_dir_all("docs/rules")?;
-                fs::write(format!("docs/rules/{}.md", rule.as_ref()), output)?;
+                fs::write(filename, output)?;
             }
         }
     }

crates/ruff_dev/src/generate_json_schema.rs

@@ -3,7 +3,9 @@
 use std::fs;
 use std::path::PathBuf;
 
-use anyhow::Result;
+use crate::generate_all::REGENERATE_ALL_COMMAND;
+use anyhow::{bail, Result};
+use pretty_assertions::StrComparison;
 use ruff::settings::options::Options;
 use schemars::schema_for;
 
@@ -14,17 +16,44 @@ pub struct Args {
     /// Write the generated table to stdout (rather than to `ruff.schema.json`).
     #[arg(long)]
     pub(crate) dry_run: bool,
+    /// Don't write to the file, check if the file is up-to-date and error if not
+    #[arg(long)]
+    pub(crate) check: bool,
 }
 
 pub fn main(args: &Args) -> Result<()> {
     let schema = schema_for!(Options);
     let schema_string = serde_json::to_string_pretty(&schema).unwrap();
+    let filename = "ruff.schema.json";
+    let schema_path = PathBuf::from(ROOT_DIR).join(filename);
 
     if args.dry_run {
         println!("{schema_string}");
+    } else if args.check {
+        let current = fs::read_to_string(schema_path)?;
+        if current == schema_string {
+            println!("up-to-date: {filename}");
+        } else {
+            let comparison = StrComparison::new(&current, &schema_string);
+            bail!("{filename} changed, please run `{REGENERATE_ALL_COMMAND}`:\n{comparison}");
+        }
     } else {
-        let file = PathBuf::from(ROOT_DIR).join("ruff.schema.json");
+        let file = schema_path;
         fs::write(file, schema_string.as_bytes())?;
     }
     Ok(())
 }
+
+#[cfg(test)]
+mod test {
+    use super::{main, Args};
+    use anyhow::Result;
+
+    #[test]
+    fn test_generate_json_schema() -> Result<()> {
+        main(&Args {
+            dry_run: false,
+            check: true,
+        })
+    }
+}