[ruff] Expand lint.external docs and add sub-diagnostic (RUF100, RUF102)

crates/ruff_linter/src/checkers/ast/mod.rs

@@ -3442,6 +3442,20 @@ impl<'a> LintContext<'a> {
         guard
     }
 
+    /// Return a [`DiagnosticGuard`] for reporting a diagnostic, with its fix title deferred, if the
+    /// corresponding rule is enabled.
+    ///
+    /// Prefer [`LintContext::report_diagnostic_if_enabled`] unless you need to attach
+    /// sub-diagnostics before the fix title. See its documentation for more details.
+    pub(crate) fn report_custom_diagnostic_if_enabled<'chk, T: Violation>(
+        &'chk self,
+        kind: T,
+        range: TextRange,
+    ) -> Option<DiagnosticGuard<'chk, 'a>> {
+        self.is_rule_enabled(T::rule())
+            .then(|| self.report_custom_diagnostic(kind, range))
+    }
+
     #[inline]
     pub(crate) const fn is_rule_enabled(&self, rule: Rule) -> bool {
         self.rules.enabled(rule)

crates/ruff_linter/src/rules/ruff/rules/invalid_rule_code.rs

@@ -47,6 +47,11 @@ impl InvalidRuleCodeKind {
 /// ```
 ///
 /// ## Options
+///
+/// This rule will flag rule codes that are unknown to Ruff, even if they are
+/// valid for other tools. You can tell Ruff to ignore such codes by configuring
+/// the list of known "external" rule codes with the following option:
+///
 /// - `lint.external`
 #[derive(ViolationMetadata)]
 #[violation_metadata(stable_since = "0.15.0")]
@@ -120,20 +125,20 @@ fn all_codes_invalid_diagnostic(
     locator: &Locator,
     context: &LintContext,
 ) {
-    context
-        .report_diagnostic(
-            InvalidRuleCode {
-                rule_code: invalid_codes
-                    .into_iter()
-                    .map(Code::as_str)
-                    .collect::<Vec<_>>()
-                    .join(", "),
-                kind: InvalidRuleCodeKind::Noqa,
-                whole_comment: true,
-            },
-            directive.range(),
-        )
-        .set_fix(Fix::safe_edit(delete_comment(directive.range(), locator)));
+    let mut diagnostic = context.report_custom_diagnostic(
+        InvalidRuleCode {
+            rule_code: invalid_codes
+                .into_iter()
+                .map(Code::as_str)
+                .collect::<Vec<_>>()
+                .join(", "),
+            kind: InvalidRuleCodeKind::Noqa,
+            whole_comment: true,
+        },
+        directive.range(),
+    );
+    diagnostic.set_fix(Fix::safe_edit(delete_comment(directive.range(), locator)));
+    diagnostic.help("Add non-Ruff rule codes to the `lint.external` configuration option");
 }
 
 fn some_codes_are_invalid_diagnostic(
@@ -142,20 +147,20 @@ fn some_codes_are_invalid_diagnostic(
     locator: &Locator,
     context: &LintContext,
 ) {
-    context
-        .report_diagnostic(
-            InvalidRuleCode {
-                rule_code: invalid_code.to_string(),
-                kind: InvalidRuleCodeKind::Noqa,
-                whole_comment: false,
-            },
-            invalid_code.range(),
-        )
-        .set_fix(Fix::safe_edit(remove_invalid_noqa(
-            codes,
-            invalid_code,
-            locator,
-        )));
+    let mut diagnostic = context.report_custom_diagnostic(
+        InvalidRuleCode {
+            rule_code: invalid_code.to_string(),
+            kind: InvalidRuleCodeKind::Noqa,
+            whole_comment: false,
+        },
+        invalid_code.range(),
+    );
+    diagnostic.set_fix(Fix::safe_edit(remove_invalid_noqa(
+        codes,
+        invalid_code,
+        locator,
+    )));
+    diagnostic.help("Add non-Ruff rule codes to the `lint.external` configuration option");
 }
 
 fn remove_invalid_noqa(codes: &Codes, invalid_code: &Code, locator: &Locator) -> Edit {

crates/ruff_linter/src/rules/ruff/rules/unused_noqa.rs

@@ -72,6 +72,11 @@ impl UnusedNOQAKind {
 /// ```
 ///
 /// ## Options
+///
+/// This rule will flag rule codes that are unknown to Ruff, even if they are
+/// valid for other tools. You can tell Ruff to ignore such codes by configuring
+/// the list of known "external" rule codes with the following option:
+///
 /// - `lint.external`
 ///
 /// ## References

crates/ruff_linter/src/rules/ruff/snapshots/ruff_linter__rules__ruff__tests__RUF102_RUF102.py.snap

@@ -10,6 +10,7 @@ RUF102 [*] Invalid rule code in `# noqa`: INVALID123
 3 | # External code
 4 | import re  # noqa: V123
   |
+help: Add non-Ruff rule codes to the `lint.external` configuration option
 help: Remove the `# noqa` comment
 1 | # Invalid code
   - import os  # noqa: INVALID123
@@ -28,6 +29,7 @@ RUF102 [*] Invalid rule code in `# noqa`: V123
 5 | # Valid noqa
 6 | import sys  # noqa: E402
   |
+help: Add non-Ruff rule codes to the `lint.external` configuration option
 help: Remove the `# noqa` comment
 1 | # Invalid code
 2 | import os  # noqa: INVALID123
@@ -48,6 +50,7 @@ RUF102 [*] Invalid rule code in `# noqa`: INVALID456
 8 | from itertools import product  # Preceeding comment # noqa: INVALID789
 9 | # Succeeding comment
   |
+help: Add non-Ruff rule codes to the `lint.external` configuration option
 help: Remove the rule code `INVALID456`
 4  | import re  # noqa: V123
 5  | # Valid noqa
@@ -68,6 +71,7 @@ RUF102 [*] Invalid rule code in `# noqa`: INVALID789
  9 | # Succeeding comment
 10 | import math # noqa: INVALID000 # Succeeding comment
    |
+help: Add non-Ruff rule codes to the `lint.external` configuration option
 help: Remove the `# noqa` comment
 5  | # Valid noqa
 6  | import sys  # noqa: E402
@@ -88,6 +92,7 @@ RUF102 [*] Invalid rule code in `# noqa`: INVALID000
 11 | # Mixed valid and invalid
 12 | from typing import List  # noqa: F401, INVALID123
    |
+help: Add non-Ruff rule codes to the `lint.external` configuration option
 help: Remove the `# noqa` comment
 7  | from functools import cache  # Preceeding comment # noqa: F401, INVALID456
 8  | from itertools import product  # Preceeding comment # noqa: INVALID789
@@ -108,6 +113,7 @@ RUF102 [*] Invalid rule code in `# noqa`: INVALID123
 13 | # Test for multiple invalid
 14 | from collections import defaultdict  # noqa: INVALID100, INVALID200, F401
    |
+help: Add non-Ruff rule codes to the `lint.external` configuration option
 help: Remove the rule code `INVALID123`
 9  | # Succeeding comment
 10 | import math # noqa: INVALID000 # Succeeding comment
@@ -128,6 +134,7 @@ RUF102 [*] Invalid rule code in `# noqa`: INVALID100
 15 | # Test for preserving valid codes when fixing
 16 | from itertools import chain  # noqa: E402, INVALID300, F401
    |
+help: Add non-Ruff rule codes to the `lint.external` configuration option
 help: Remove the rule code `INVALID100`
 11 | # Mixed valid and invalid
 12 | from typing import List  # noqa: F401, INVALID123
@@ -148,6 +155,7 @@ RUF102 [*] Invalid rule code in `# noqa`: INVALID200
 15 | # Test for preserving valid codes when fixing
 16 | from itertools import chain  # noqa: E402, INVALID300, F401
    |
+help: Add non-Ruff rule codes to the `lint.external` configuration option
 help: Remove the rule code `INVALID200`
 11 | # Mixed valid and invalid
 12 | from typing import List  # noqa: F401, INVALID123
@@ -168,6 +176,7 @@ RUF102 [*] Invalid rule code in `# noqa`: INVALID300
 17 | # Test for mixed code types
 18 | import json  # noqa: E402, INVALID400, V100
    |
+help: Add non-Ruff rule codes to the `lint.external` configuration option
 help: Remove the rule code `INVALID300`
 13 | # Test for multiple invalid
 14 | from collections import defaultdict  # noqa: INVALID100, INVALID200, F401
@@ -188,6 +197,7 @@ RUF102 [*] Invalid rule code in `# noqa`: INVALID400
 19 | # Test for rule redirects
 20 | import pandas as pd  # noqa: TCH002
    |
+help: Add non-Ruff rule codes to the `lint.external` configuration option
 help: Remove the rule code `INVALID400`
 15 | # Test for preserving valid codes when fixing
 16 | from itertools import chain  # noqa: E402, INVALID300, F401
@@ -208,6 +218,7 @@ RUF102 [*] Invalid rule code in `# noqa`: V100
 19 | # Test for rule redirects
 20 | import pandas as pd  # noqa: TCH002
    |
+help: Add non-Ruff rule codes to the `lint.external` configuration option
 help: Remove the rule code `V100`
 15 | # Test for preserving valid codes when fixing
 16 | from itertools import chain  # noqa: E402, INVALID300, F401
@@ -226,6 +237,7 @@ RUF102 [*] Invalid rule code in `# noqa`: INVALID123
 22 | import pathlib  # noqa: INVALID123 some reason
    |                 ^^^^^^^^^^^^^^^^^^
    |
+help: Add non-Ruff rule codes to the `lint.external` configuration option
 help: Remove the `# noqa` comment
 19 | # Test for rule redirects
 20 | import pandas as pd  # noqa: TCH002

crates/ruff_linter/src/rules/ruff/snapshots/ruff_linter__rules__ruff__tests__invalid_rule_code_external_rules.snap

@@ -10,6 +10,7 @@ RUF102 [*] Invalid rule code in `# noqa`: INVALID123
 3 | # External code
 4 | import re  # noqa: V123
   |
+help: Add non-Ruff rule codes to the `lint.external` configuration option
 help: Remove the `# noqa` comment
 1 | # Invalid code
   - import os  # noqa: INVALID123
@@ -28,6 +29,7 @@ RUF102 [*] Invalid rule code in `# noqa`: INVALID456
 8 | from itertools import product  # Preceeding comment # noqa: INVALID789
 9 | # Succeeding comment
   |
+help: Add non-Ruff rule codes to the `lint.external` configuration option
 help: Remove the rule code `INVALID456`
 4  | import re  # noqa: V123
 5  | # Valid noqa
@@ -48,6 +50,7 @@ RUF102 [*] Invalid rule code in `# noqa`: INVALID789
  9 | # Succeeding comment
 10 | import math # noqa: INVALID000 # Succeeding comment
    |
+help: Add non-Ruff rule codes to the `lint.external` configuration option
 help: Remove the `# noqa` comment
 5  | # Valid noqa
 6  | import sys  # noqa: E402
@@ -68,6 +71,7 @@ RUF102 [*] Invalid rule code in `# noqa`: INVALID000
 11 | # Mixed valid and invalid
 12 | from typing import List  # noqa: F401, INVALID123
    |
+help: Add non-Ruff rule codes to the `lint.external` configuration option
 help: Remove the `# noqa` comment
 7  | from functools import cache  # Preceeding comment # noqa: F401, INVALID456
 8  | from itertools import product  # Preceeding comment # noqa: INVALID789
@@ -88,6 +92,7 @@ RUF102 [*] Invalid rule code in `# noqa`: INVALID123
 13 | # Test for multiple invalid
 14 | from collections import defaultdict  # noqa: INVALID100, INVALID200, F401
    |
+help: Add non-Ruff rule codes to the `lint.external` configuration option
 help: Remove the rule code `INVALID123`
 9  | # Succeeding comment
 10 | import math # noqa: INVALID000 # Succeeding comment
@@ -108,6 +113,7 @@ RUF102 [*] Invalid rule code in `# noqa`: INVALID100
 15 | # Test for preserving valid codes when fixing
 16 | from itertools import chain  # noqa: E402, INVALID300, F401
    |
+help: Add non-Ruff rule codes to the `lint.external` configuration option
 help: Remove the rule code `INVALID100`
 11 | # Mixed valid and invalid
 12 | from typing import List  # noqa: F401, INVALID123
@@ -128,6 +134,7 @@ RUF102 [*] Invalid rule code in `# noqa`: INVALID200
 15 | # Test for preserving valid codes when fixing
 16 | from itertools import chain  # noqa: E402, INVALID300, F401
    |
+help: Add non-Ruff rule codes to the `lint.external` configuration option
 help: Remove the rule code `INVALID200`
 11 | # Mixed valid and invalid
 12 | from typing import List  # noqa: F401, INVALID123
@@ -148,6 +155,7 @@ RUF102 [*] Invalid rule code in `# noqa`: INVALID300
 17 | # Test for mixed code types
 18 | import json  # noqa: E402, INVALID400, V100
    |
+help: Add non-Ruff rule codes to the `lint.external` configuration option
 help: Remove the rule code `INVALID300`
 13 | # Test for multiple invalid
 14 | from collections import defaultdict  # noqa: INVALID100, INVALID200, F401
@@ -168,6 +176,7 @@ RUF102 [*] Invalid rule code in `# noqa`: INVALID400
 19 | # Test for rule redirects
 20 | import pandas as pd  # noqa: TCH002
    |
+help: Add non-Ruff rule codes to the `lint.external` configuration option
 help: Remove the rule code `INVALID400`
 15 | # Test for preserving valid codes when fixing
 16 | from itertools import chain  # noqa: E402, INVALID300, F401
@@ -186,6 +195,7 @@ RUF102 [*] Invalid rule code in `# noqa`: INVALID123
 22 | import pathlib  # noqa: INVALID123 some reason
    |                 ^^^^^^^^^^^^^^^^^^
    |
+help: Add non-Ruff rule codes to the `lint.external` configuration option
 help: Remove the `# noqa` comment
 19 | # Test for rule redirects
 20 | import pandas as pd  # noqa: TCH002

crates/ruff_linter/src/rules/ruff/snapshots/ruff_linter__rules__ruff__tests__range_suppressions.snap

@@ -327,6 +327,7 @@ RUF102 [*] Invalid rule code in suppression: YF829
 97 |     # ruff: enable[YF829]
    |                    -----
    |
+help: Add non-Ruff rule codes to the `lint.external` configuration option
 help: Remove the suppression comment
 90 | 
 91 | def f():
@@ -352,6 +353,7 @@ RUF102 [*] Invalid rule code in suppression: RQW320
    |                          ------
 97 |     # ruff: enable[YF829]
    |
+help: Add non-Ruff rule codes to the `lint.external` configuration option
 help: Remove the rule code `RQW320`
 91 | def f():
 92 |     # Unknown rule codes