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

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,
+        })
+    }
+}