Background

Our new diagnostic system has the ability to attach additional information to the main diagnostic. The two main types of additional information are:

• Secondary annotations
  These are rendered as additional underlined ranges in the snippet for the main diagnostic:

   PLC0206 Extracting value from dictionary without calling `.items()`
     --> dict_index_missing_items.py:59:5
      |
   58 |
   59 | for instrument in ORCHESTRA:
      |     ^^^^^^^^^^^^^^^^^^^^^^^  <- primary diagnostic range
   60 |     data = json.dumps(
   61 |         {
   62 |             "instrument": instrument,
   63 |             "section": ORCHESTRA[instrument],
      |                        ---------------------  <- secondary annotation
   64 |         }
   65 |     )
   help: Use `for instrument, value in ORCHESTRA.items()` instead
  

  and can be added in most lint rules via the DiagnosticGuard::secondary_annotation helper.

  The example above is from [pylint] Improve diagnostic range for PLC0206 #22312.

• Sub-diagnostics
  The help: ... line above is actually a simple example of a sub-diagnostic without its own code snippet. For simple messages, you can use the Diagnostic::info or Diagnostic::help methods via the DiagnosticGuard deref implementation.

  Sub-diagnostics can, however, include almost all of the kinds of information as a primary diagnostic. We don't have any examples of this in Ruff yet, but you can find some in ty.

  I think we'll mostly be okay with secondary annotations or simple sub-diagnostics in Ruff, but it's possible to produce these if needed.

Places to use new diagnostics

This is a list of places we've thought about using the new diagnostics. Note that most of these are follow-up comments on merged PRs, so the fact that they're merged doesn't mean that the diagnostics have been updated.

• Control flow: return and raise #17121 (comment)
• [syntax-errors] Detect duplicate keys in match mapping patterns #17129 (comment)
• Implement Invalid rule provided as rule RUF102 with --fix #17138 (comment)
• [flake8-pyi] Significantly improve accuracy of PYI019 if preview mode is enabled #15888 (comment)
• Add lint rule for calling chmod with non-octal integers #18541 (comment)
  • [ruff] Add sub-diagnostics with permissions (RUF064) #22972
• TC004 diagnostics/docs should clarify that type hints can be executed at run-time #16490 (comment)
  I've already done some of the scouting work here, so it could be a great place to start :)
• FAST002 (FastAPI dependency without Annotated) could be made even smarter #22188 (comment)

Examples

Here are a couple of example PRs showing how to use secondary annotations:

• [pylint] Improve diagnostic range for PLC0206 #22312
• [pyflakes] Add secondary annotation showing previous definition (F811) #19900

One thing to watch out for is that changing the primary diagnostic range can easily be a breaking change, so for the most part we only want to add new annotations here, not change the existing ones.