Document when a rule was added

crates/ruff/src/commands/rule.rs

@@ -25,6 +25,7 @@ struct Explanation<'a> {
     explanation: Option<&'a str>,
     preview: bool,
     status: RuleGroup,
+    source_location: SourceLocation,
 }
 
 impl<'a> Explanation<'a> {
@@ -43,6 +44,10 @@ impl<'a> Explanation<'a> {
             explanation: rule.explanation(),
             preview: rule.is_preview(),
             status: rule.group(),
+            source_location: SourceLocation {
+                file: rule.file(),
+                line: rule.line(),
+            },
         }
     }
 }
@@ -127,3 +132,14 @@ pub(crate) fn rules(format: HelpFormat) -> Result<()> {
     }
     Ok(())
 }
+
+/// The location of the rule's implementation in the Ruff source tree, relative to the repository
+/// root.
+///
+/// For most rules this will point to the `#[derive(ViolationMetadata)]` line above the rule's
+/// struct.
+#[derive(Serialize)]
+struct SourceLocation {
+    file: &'static str,
+    line: u32,
+}

crates/ruff/tests/integration_test.rs

@@ -953,7 +953,11 @@ fn rule_f401() {
 
 #[test]
 fn rule_f401_output_json() {
-    assert_cmd_snapshot!(ruff_cmd().args(["rule", "F401", "--output-format", "json"]));
+    insta::with_settings!({filters => vec![
+        (r#"("file": ")[^"]+(",)"#, "$1<FILE>$2"),
+    ]}, {
+        assert_cmd_snapshot!(ruff_cmd().args(["rule", "F401", "--output-format", "json"]));
+    });
 }
 
 #[test]

crates/ruff/tests/snapshots/integration_test__rule_f401_output_json.snap

@@ -25,6 +25,14 @@ exit_code: 0
   "fix_availability": "Sometimes",
   "explanation": "## What it does\nChecks for unused imports.\n\n## Why is this bad?\nUnused imports add a performance overhead at runtime, and risk creating\nimport cycles. They also increase the cognitive load of reading the code.\n\nIf an import statement is used to check for the availability or existence\nof a module, consider using `importlib.util.find_spec` instead.\n\nIf an import statement is used to re-export a symbol as part of a module's\npublic interface, consider using a \"redundant\" import alias, which\ninstructs Ruff (and other tools) to respect the re-export, and avoid\nmarking it as unused, as in:\n\n```python\nfrom module import member as member\n```\n\nAlternatively, you can use `__all__` to declare a symbol as part of the module's\ninterface, as in:\n\n```python\n# __init__.py\nimport some_module\n\n__all__ = [\"some_module\"]\n```\n\n## Preview\nWhen [preview] is enabled (and certain simplifying assumptions\nare met), we analyze all import statements for a given module\nwhen determining whether an import is used, rather than simply\nthe last of these statements. This can result in both different and\nmore import statements being marked as unused.\n\nFor example, if a module consists of\n\n```python\nimport a\nimport a.b\n```\n\nthen both statements are marked as unused under [preview], whereas\nonly the second is marked as unused under stable behavior.\n\nAs another example, if a module consists of\n\n```python\nimport a.b\nimport a\n\na.b.foo()\n```\n\nthen a diagnostic will only be emitted for the first line under [preview],\nwhereas a diagnostic would only be emitted for the second line under\nstable behavior.\n\nNote that this behavior is somewhat subjective and is designed\nto conform to the developer's intuition rather than Python's actual\nexecution. To wit, the statement `import a.b` automatically executes\n`import a`, so in some sense `import a` is _always_ redundant\nin the presence of `import a.b`.\n\n\n## Fix safety\n\nFixes to remove unused imports are safe, except in `__init__.py` files.\n\nApplying fixes to `__init__.py` files is currently in preview. The fix offered depends on the\ntype of the unused import. Ruff will suggest a safe fix to export first-party imports with\neither a redundant alias or, if already present in the file, an `__all__` entry. If multiple\n`__all__` declarations are present, Ruff will not offer a fix. Ruff will suggest an unsafe fix\nto remove third-party and standard library imports -- the fix is unsafe because the module's\ninterface changes.\n\nSee [this FAQ section](https://docs.astral.sh/ruff/faq/#how-does-ruff-determine-which-of-my-imports-are-first-party-third-party-etc)\nfor more details on how Ruff\ndetermines whether an import is first or third-party.\n\n## Example\n\n```python\nimport numpy as np  # unused import\n\n\ndef area(radius):\n    return 3.14 * radius**2\n```\n\nUse instead:\n\n```python\ndef area(radius):\n    return 3.14 * radius**2\n```\n\nTo check the availability of a module, use `importlib.util.find_spec`:\n\n```python\nfrom importlib.util import find_spec\n\nif find_spec(\"numpy\") is not None:\n    print(\"numpy is installed\")\nelse:\n    print(\"numpy is not installed\")\n```\n\n## Options\n- `lint.ignore-init-module-imports`\n- `lint.pyflakes.allowed-unused-imports`\n\n## References\n- [Python documentation: `import`](https://docs.python.org/3/reference/simple_stmts.html#the-import-statement)\n- [Python documentation: `importlib.util.find_spec`](https://docs.python.org/3/library/importlib.html#importlib.util.find_spec)\n- [Typing documentation: interface conventions](https://typing.python.org/en/latest/spec/distributing.html#library-interface-public-and-private-symbols)\n\n[preview]: https://docs.astral.sh/ruff/preview/\n",
   "preview": false,
-  "status": "Stable"
+  "status": {
+    "Stable": {
+      "since": "v0.0.18"
+    }
+  },
+  "source_location": {
+    "file": "<FILE>",
+    "line": 145
+  }
 }
 ----- stderr -----

crates/ruff_dev/src/generate_docs.rs

@@ -8,6 +8,7 @@ use std::path::PathBuf;
 use anyhow::Result;
 use itertools::Itertools;
 use regex::{Captures, Regex};
+use ruff_linter::codes::RuleGroup;
 use strum::IntoEnumIterator;
 
 use ruff_linter::FixAvailability;
@@ -31,6 +32,47 @@ pub(crate) fn main(args: &Args) -> Result<()> {
 
             let _ = writeln!(&mut output, "# {} ({})", rule.name(), rule.noqa_code());
 
+            let status_text = match rule.group() {
+                RuleGroup::Stable { since } => {
+                    format!(
+                        r#"Added in <a href="https://github.com/astral-sh/ruff/releases/tag/{since}">{since}</a>"#
+                    )
+                }
+                RuleGroup::Preview { since } => {
+                    format!(
+                        r#"Preview (since <a href="https://github.com/astral-sh/ruff/releases/tag/{since}">{since}</a>)"#
+                    )
+                }
+                RuleGroup::Deprecated { since } => {
+                    format!(
+                        r#"Deprecated (since <a href="https://github.com/astral-sh/ruff/releases/tag/{since}">{since}</a>)"#
+                    )
+                }
+                RuleGroup::Removed { since } => {
+                    format!(
+                        r#"Removed (since <a href="https://github.com/astral-sh/ruff/releases/tag/{since}">{since}</a>)"#
+                    )
+                }
+            };
+
+            let _ = writeln!(
+                &mut output,
+                r#"<small>
+{status_text} ·
+<a href="https://github.com/astral-sh/ruff/issues?q=sort%3Aupdated-desc%20is%3Aissue%20is%3Aopen%20(%27{encoded_name}%27%20OR%20{rule_code})" target="_blank">Related issues</a> ·
+<a href="https://github.com/astral-sh/ruff/blob/main/{file}#L{line}" target="_blank">View source</a>
+</small>
+
+"#,
+                encoded_name =
+                    url::form_urlencoded::byte_serialize(rule.name().as_str().as_bytes())
+                        .collect::<String>(),
+                rule_code = rule.noqa_code(),
+                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_dev/src/generate_rules_table.rs

@@ -32,20 +32,24 @@ fn generate_table(table_out: &mut String, rules: impl IntoIterator<Item = Rule>,
     table_out.push('\n');
     for rule in rules {
         let status_token = match rule.group() {
-            RuleGroup::Removed => {
+            RuleGroup::Removed { since } => {
                 format!(
-                    "<span {SYMBOL_STYLE} title='Rule has been removed'>{REMOVED_SYMBOL}</span>"
+                    "<span {SYMBOL_STYLE} title='Rule was removed in {since}'>{REMOVED_SYMBOL}</span>"
                 )
             }
-            RuleGroup::Deprecated => {
+            RuleGroup::Deprecated { since } => {
                 format!(
-                    "<span {SYMBOL_STYLE} title='Rule has been deprecated'>{WARNING_SYMBOL}</span>"
+                    "<span {SYMBOL_STYLE} title='Rule has been deprecated since {since}'>{WARNING_SYMBOL}</span>"
                 )
             }
-            RuleGroup::Preview => {
-                format!("<span {SYMBOL_STYLE} title='Rule is in preview'>{PREVIEW_SYMBOL}</span>")
+            RuleGroup::Preview { since } => {
+                format!(
+                    "<span {SYMBOL_STYLE} title='Rule has been in preview since {since}'>{PREVIEW_SYMBOL}</span>"
+                )
+            }
+            RuleGroup::Stable { since } => {
+                format!("<span {SYMBOL_STYLE} title='Rule has been stable since {since}'></span>")
             }
-            RuleGroup::Stable => format!("<span {SYMBOL_STYLE}></span>"),
         };
 
         let fix_token = match rule.fixable() {