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

Summary
--

We've gotten a couple of recent reports about suppressing both of these
rules (#23191 and #23267 at least), so I think it's worth trying to
provide more
information in the diagnostics and also in the documentation. The
connection to
`lint.external` was at least documented, but the rule docs themselves
didn't
really help unless you clicked through to the setting itself.

I'm not 100% sold on this sub-diagnostic message. It feels a bit
verbose, but I
like that it's explicit. Given full control over the placement, I'd
probably put
it below the fix diff, but this seems like the best option we currently
have
available.

Test Plan
--

Updated snapshot tests

Author: ntBre

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