Document when a rule was added

add_metadata.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+import csv
+import glob
+import json
+import re
+import subprocess
+from pathlib import Path
+
+Rule = str
+Version = str
+
+
+def kebab_to_pascal(name):
+    return "".join(word.capitalize() for word in name.split("-"))
+
+
+def load_rules() -> dict[Rule, str]:
+    rules = json.loads(
+        subprocess.run(
+            ["ruff", "rule", "--all", "--output-format", "json"],
+            capture_output=True,
+            check=True,
+        ).stdout
+    )
+
+    return {rule["code"]: kebab_to_pascal(rule["name"]) for rule in rules}
+
+
+def load_versions() -> dict[Rule, Version]:
+    versions = {}
+    with open("ruff_rules_metadata.csv") as f:
+        reader = csv.reader(f)
+        for i, line in enumerate(reader):
+            if i == 0:
+                continue
+            rule, version, _ = line
+            versions[rule] = version
+
+    return versions
+
+
+if __name__ == "__main__":
+    rules = load_rules()
+    versions = load_versions()
+
+    for rule, name in rules.items():
+        print(f"searching for {rule}")
+        pattern = re.compile(rf"pub(\(crate\))? struct {name}( [{{]|;|<|\()", re.I)
+        for path in glob.glob("crates/ruff_linter/src/rules/**/*.rs", recursive=True):
+            path = Path(path)
+            contents = path.read_text()
+            if pattern.search(contents):
+                new_contents = pattern.sub(
+                    rf'#[violation_metadata(version = "{versions[rule]}")]\n\g<0>',
+                    contents,
+                )
+                path.write_text(new_contents)
+                break
+        else:
+            raise ValueError(f"failed to locate definition for {name}")

crates/ruff_dev/src/generate_docs.rs

@@ -31,6 +31,25 @@ pub(crate) fn main(args: &Args) -> Result<()> {
 
             let _ = writeln!(&mut output, "# {} ({})", rule.name(), rule.noqa_code());
 
+            let _ = writeln!(
+                &mut output,
+                r#"<small>
+Added in <a href="https://github.com/astral-sh/ruff/releases/tag/{version}">{version}</a> ·
+<a href="https://github.com/astral-sh/ruff/issues?q=sort%3Aupdated-desc%20is%3Aissue%20is%3Aopen%20{encoded_name}" target="_blank">Related issues</a> ·
+<a href="https://github.com/astral-sh/ruff/blob/main/{file}#L{line}" target="_blank">View source</a>
+</small>
+
+"#,
+                version = rule.version().unwrap_or(env!("CARGO_PKG_VERSION")),
+                encoded_name =
+                    url::form_urlencoded::byte_serialize(rule.name().as_str().as_bytes())
+                        .collect::<String>(),
+                file =
+                    url::form_urlencoded::byte_serialize(rule.file().replace('\\', "/").as_bytes())
+                        .collect::<String>(),
+                line = rule.line(),
+            );
+
             let (linter, _) = Linter::parse_code(&rule.noqa_code().to_string()).unwrap();
             if linter.url().is_some() {
                 let common_prefix: String = match linter.common_prefix() {

crates/ruff_linter/src/violation.rs

@@ -32,6 +32,15 @@ pub trait ViolationMetadata {
     /// Returns an explanation of what this violation catches,
     /// why it's bad, and what users should do instead.
     fn explain() -> Option<&'static str>;
+
+    /// The Ruff version when a rule was first introduced, e.g. 0.1.2.
+    fn version() -> Option<&'static str>;
+
+    /// The file where the violation is declared.
+    fn file() -> &'static str;
+
+    /// The 1-based line where the violation is declared.
+    fn line() -> u32;
 }
 
 pub trait Violation: ViolationMetadata + Sized {

crates/ruff_macros/src/lib.rs

@@ -82,7 +82,7 @@ pub fn cache_key(input: TokenStream) -> TokenStream {
     TokenStream::from(stream)
 }
 
-#[proc_macro_derive(ViolationMetadata)]
+#[proc_macro_derive(ViolationMetadata, attributes(violation_metadata))]
 pub fn derive_violation_metadata(item: TokenStream) -> TokenStream {
     let input: DeriveInput = parse_macro_input!(item);
 

crates/ruff_macros/src/map_codes.rs

@@ -403,6 +403,9 @@ fn register_rules<'a>(input: impl Iterator<Item = &'a Rule>) -> TokenStream {
     let mut rule_message_formats_match_arms = quote!();
     let mut rule_fixable_match_arms = quote!();
     let mut rule_explanation_match_arms = quote!();
+    let mut rule_version_match_arms = quote!();
+    let mut rule_file_match_arms = quote!();
+    let mut rule_line_match_arms = quote!();
 
     for Rule {
         name, attrs, path, ..
@@ -420,6 +423,15 @@ fn register_rules<'a>(input: impl Iterator<Item = &'a Rule>) -> TokenStream {
             quote! {#(#attrs)* Self::#name => <#path as crate::Violation>::FIX_AVAILABILITY,},
         );
         rule_explanation_match_arms.extend(quote! {#(#attrs)* Self::#name => #path::explain(),});
+        rule_version_match_arms.extend(
+            quote! {#(#attrs)* Self::#name => <#path as crate::ViolationMetadata>::version(),},
+        );
+        rule_file_match_arms.extend(
+            quote! {#(#attrs)* Self::#name => <#path as crate::ViolationMetadata>::file(),},
+        );
+        rule_line_match_arms.extend(
+            quote! {#(#attrs)* Self::#name => <#path as crate::ViolationMetadata>::line(),},
+        );
     }
 
     quote! {
@@ -455,6 +467,18 @@ fn register_rules<'a>(input: impl Iterator<Item = &'a Rule>) -> TokenStream {
             pub const fn fixable(&self) -> crate::FixAvailability {
                 match self { #rule_fixable_match_arms }
             }
+
+            pub fn version(&self) -> Option<&'static str> {
+                match self { #rule_version_match_arms }
+            }
+
+            pub fn file(&self) -> &'static str {
+                match self { #rule_file_match_arms }
+            }
+
+            pub fn line(&self) -> u32 {
+                match self { #rule_line_match_arms }
+            }
         }
     }
 }

crates/ruff_macros/src/violation_metadata.rs

@@ -5,6 +5,11 @@ use syn::{Attribute, DeriveInput, Error, Lit, LitStr, Meta};
 pub(crate) fn violation_metadata(input: DeriveInput) -> syn::Result<TokenStream> {
     let docs = get_docs(&input.attrs)?;
 
+    let version = match get_version(&input.attrs)? {
+        Some(version) => quote!(Some(#version)),
+        None => quote!(None),
+    };
+
     let name = input.ident;
 
     let (impl_generics, ty_generics, where_clause) = &input.generics.split_for_impl();
@@ -20,6 +25,18 @@ pub(crate) fn violation_metadata(input: DeriveInput) -> syn::Result<TokenStream>
             fn explain() -> Option<&'static str> {
                 Some(#docs)
             }
+
+            fn version() -> Option<&'static str> {
+                #version
+            }
+
+            fn file() -> &'static str {
+                file!()
+            }
+
+            fn line() -> u32 {
+                line!()
+            }
         }
     })
 }
@@ -43,6 +60,27 @@ fn get_docs(attrs: &[Attribute]) -> syn::Result<String> {
     Ok(explanation)
 }
 
+/// Extract the version attribute as a string.
+fn get_version(attrs: &[Attribute]) -> syn::Result<Option<String>> {
+    let mut version = None;
+    for attr in attrs {
+        if attr.path().is_ident("violation_metadata") {
+            attr.parse_nested_meta(|meta| {
+                if meta.path.is_ident("version") {
+                    let lit: LitStr = meta.value()?.parse()?;
+                    version = Some(lit.value());
+                    return Ok(());
+                }
+                Err(Error::new_spanned(
+                    attr,
+                    "unimplemented violation metadata option",
+                ))
+            })?;
+        }
+    }
+    Ok(version)
+}
+
 fn parse_attr<'a, const LEN: usize>(
     path: [&'static str; LEN],
     attr: &'a Attribute,