Auto-generate environment variable references for ty (#19205)

## Summary

This PR mirrors the environment variable implementation we have in uv:
efc361223c/crates/uv-static/src/env_vars.rs (L6-L7).

See: https://github.com/astral-sh/ty/issues/773.

crates/ruff_dev/src/generate_all.rs

@@ -4,7 +4,7 @@ use anyhow::Result;
 
 use crate::{
     generate_cli_help, generate_docs, generate_json_schema, generate_ty_cli_reference,
-    generate_ty_options, generate_ty_rules, generate_ty_schema,
+    generate_ty_env_vars_reference, generate_ty_options, generate_ty_rules, generate_ty_schema,
 };
 
 pub(crate) const REGENERATE_ALL_COMMAND: &str = "cargo dev generate-all";
@@ -44,5 +44,8 @@ pub(crate) fn main(args: &Args) -> Result<()> {
     generate_ty_options::main(&generate_ty_options::Args { mode: args.mode })?;
     generate_ty_rules::main(&generate_ty_rules::Args { mode: args.mode })?;
     generate_ty_cli_reference::main(&generate_ty_cli_reference::Args { mode: args.mode })?;
+    generate_ty_env_vars_reference::main(&generate_ty_env_vars_reference::Args {
+        mode: args.mode,
+    })?;
     Ok(())
 }

crates/ruff_dev/src/generate_ty_env_vars_reference.rs

@@ -0,0 +1,119 @@
+//! Generate the environment variables reference from `ty_static::EnvVars`.
+
+use std::collections::BTreeSet;
+use std::fs;
+use std::path::PathBuf;
+
+use anyhow::bail;
+use pretty_assertions::StrComparison;
+
+use ty_static::EnvVars;
+
+use crate::generate_all::Mode;
+
+#[derive(clap::Args)]
+pub(crate) struct Args {
+    #[arg(long, default_value_t, value_enum)]
+    pub(crate) mode: Mode,
+}
+
+pub(crate) fn main(args: &Args) -> anyhow::Result<()> {
+    let reference_string = generate();
+    let filename = "environment.md";
+    let reference_path = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
+        .parent()
+        .unwrap()
+        .parent()
+        .unwrap()
+        .join("crates")
+        .join("ty")
+        .join("docs")
+        .join(filename);
+
+    match args.mode {
+        Mode::DryRun => {
+            println!("{reference_string}");
+        }
+        Mode::Check => match fs::read_to_string(&reference_path) {
+            Ok(current) => {
+                if current == reference_string {
+                    println!("Up-to-date: {filename}");
+                } else {
+                    let comparison = StrComparison::new(&current, &reference_string);
+                    bail!(
+                        "{filename} changed, please run `cargo dev generate-ty-env-vars-reference`:\n{comparison}"
+                    );
+                }
+            }
+            Err(err) if err.kind() == std::io::ErrorKind::NotFound => {
+                bail!(
+                    "{filename} not found, please run `cargo dev generate-ty-env-vars-reference`"
+                );
+            }
+            Err(err) => {
+                bail!(
+                    "{filename} changed, please run `cargo dev generate-ty-env-vars-reference`:\n{err}"
+                );
+            }
+        },
+        Mode::Write => {
+            // Ensure the docs directory exists
+            if let Some(parent) = reference_path.parent() {
+                fs::create_dir_all(parent)?;
+            }
+
+            match fs::read_to_string(&reference_path) {
+                Ok(current) => {
+                    if current == reference_string {
+                        println!("Up-to-date: {filename}");
+                    } else {
+                        println!("Updating: {filename}");
+                        fs::write(&reference_path, reference_string.as_bytes())?;
+                    }
+                }
+                Err(err) if err.kind() == std::io::ErrorKind::NotFound => {
+                    println!("Updating: {filename}");
+                    fs::write(&reference_path, reference_string.as_bytes())?;
+                }
+                Err(err) => {
+                    bail!(
+                        "{filename} changed, please run `cargo dev generate-ty-env-vars-reference`:\n{err}"
+                    );
+                }
+            }
+        }
+    }
+
+    Ok(())
+}
+
+fn generate() -> String {
+    let mut output = String::new();
+
+    output.push_str("# Environment variables\n\n");
+
+    // Partition and sort environment variables into TY_ and external variables.
+    let (ty_vars, external_vars): (BTreeSet<_>, BTreeSet<_>) = EnvVars::metadata()
+        .iter()
+        .partition(|(var, _)| var.starts_with("TY_"));
+
+    output.push_str("ty defines and respects the following environment variables:\n\n");
+
+    for (var, doc) in ty_vars {
+        output.push_str(&render(var, doc));
+    }
+
+    output.push_str("## Externally-defined variables\n\n");
+    output.push_str("ty also reads the following externally defined environment variables:\n\n");
+
+    for (var, doc) in external_vars {
+        output.push_str(&render(var, doc));
+    }
+
+    output
+}
+
+/// Render an environment variable and its documentation.
+fn render(var: &str, doc: &str) -> String {
+    format!("### `{var}`\n\n{doc}\n\n")
+}

crates/ruff_dev/src/main.rs

@@ -18,6 +18,7 @@ mod generate_json_schema;
 mod generate_options;
 mod generate_rules_table;
 mod generate_ty_cli_reference;
+mod generate_ty_env_vars_reference;
 mod generate_ty_options;
 mod generate_ty_rules;
 mod generate_ty_schema;
@@ -53,6 +54,8 @@ enum Command {
     /// Generate a Markdown-compatible listing of configuration options.
     GenerateOptions,
     GenerateTyOptions(generate_ty_options::Args),
+    /// Generate environment variables reference for ty.
+    GenerateTyEnvVarsReference(generate_ty_env_vars_reference::Args),
     /// Generate CLI help.
     GenerateCliHelp(generate_cli_help::Args),
     /// Generate Markdown docs.
@@ -98,6 +101,7 @@ fn main() -> Result<ExitCode> {
         Command::GenerateTyRules(args) => generate_ty_rules::main(&args)?,
         Command::GenerateOptions => println!("{}", generate_options::generate()),
         Command::GenerateTyOptions(args) => generate_ty_options::main(&args)?,
+        Command::GenerateTyEnvVarsReference(args) => generate_ty_env_vars_reference::main(&args)?,
         Command::GenerateCliHelp(args) => generate_cli_help::main(&args)?,
         Command::GenerateDocs(args) => generate_docs::main(&args)?,
         Command::PrintAST(args) => print_ast::main(&args)?,