Vendor latest annotate-snippets by epage · Pull Request #27033 · astral-sh/ruff

epage · 2026-07-20T20:49:08Z

Summary

This is a first step towards #20411. After this, we would work to either upstream changes or adjust things within Ruff.

Performance improvements have already been upstreamed (rust-lang/annotate-snippets-rs#437, rust-lang/annotate-snippets-rs#440)

Re-implemented the following from the fork:

Hidden snippets (A way to infer line/column for Origin rust-lang/annotate-snippets-rs#448)
Renderer-level disabling of hyperlinks (Title URLs/Hyperlinks are emitted even for Renderer::plain() rust-lang/annotate-snippets-rs#393)
Jupyter cell indices (More levels to Origin rust-lang/annotate-snippets-rs#449)
Fixable mark (Footnotes for titles rust-lang/annotate-snippets-rs#450)
lineno_offset (maybe not needed if Move diff rendering into annotate-snippets #20648 is taken care of)
anonymized lines affects origin (Anonymize the line within origin rust-lang/annotate-snippets-rs#451)
cut indicator (maybe not needed if we can switch to unicode renderer)

Additional hacks to minimize behavior change include

Adjust upstream's hidden severity behavior to match Ruff's (Hiding a Level shouldn't hide the label rust-lang/annotate-snippets-rs#452)
How newlines are annotated (Annotating newline characters leads to busy looking multi-line span rust-lang/annotate-snippets-rs#454)
To not indent for line numbers when none will be present (Elements without line numbers are still indented as if there is a single-digit line number rust-lang/annotate-snippets-rs#453)
Enabling simd by default

All of the above represents work that needs to be resolved to address #20411.

lib.name hack is used to simplify maintenance with the assumption that we'll continue working towards #20411.

Behavior changes that were included

Tweak when implicit padding lines are present
Fix Origin's line/column is now derived from the primary annotation
Make consistent the rendering of primary/context annotations
Fix snippets to show up for empty source (but may degrade ruff format --check outputs wrong line line/column numbers on syntax errors #24528)
Fix handling of term width
Fix rendering of annotations between newline and first character (granted, maybe the caller is wrong)
Tweak multiline annotation markers

New or upcoming features annotate-snippets features that we will be able to leverage by moving this forward

AnnotationKind::Visible to improve the quality of built-in code-folding if Ruff were to switch to it
DecorStyle::Unicode
(upcoming) No-graphiscs mode for screen readers (may also be useful for AIs)

Deferred:

Moving related Groups into the same Report
Using secondary_title for any Group after the first in a Report
Using a Snippet, instead of titles, for "virtual code" like Vendor latest annotate-snippets #27033 (comment)
Switching hidden snippets to Origin

Test Plan

Within cpython, I ran

$ hyperfine -i "../../ruff/target-baseline/release/ruff check" "../../ruff/target-update/release/ruff check" -N -m20 --output=null
Benchmark 1: ../../ruff/target-baseline/release/ruff check
  Time (mean ± σ):      27.5 ms ±   1.1 ms    [User: 33.0 ms, System: 108.4 ms]
  Range (min … max):    25.0 ms …  31.7 ms    94 runs

  Warning: Ignoring non-zero exit code.

Benchmark 2: ../../ruff/target-update/release/ruff check
  Time (mean ± σ):      28.1 ms ±   2.0 ms    [User: 33.4 ms, System: 105.7 ms]
  Range (min … max):    24.8 ms …  38.9 ms    102 runs

  Warning: Ignoring non-zero exit code.
  Warning: Statistical outliers were detected. Consider re-running this benchmark on a quiet system without any interferences from other programs. It might help to use t
he '--warmup' or '--prepare' options.

Summary
  ../../ruff/target-baseline/release/ruff check ran
    1.03 ± 0.08 times faster than ../../ruff/target-update/release/ruff check

Before:

After:

astral-sh-bot · 2026-07-20T20:51:35Z

Typing conformance results

No changes detected ✅

Current numbers

The percentage of diagnostics emitted that were expected errors held steady at 96.84%. The percentage of expected errors that received a diagnostic held steady at 92.11%. The number of fully passing files held steady at 99/133.

astral-sh-bot · 2026-07-20T20:52:33Z

Memory usage report

Memory usage unchanged ✅

astral-sh-bot · 2026-07-20T20:59:40Z

`ecosystem-analyzer` results

No diagnostic changes detected ✅

Full report with detailed diff (timing results)

astral-sh-bot · 2026-07-20T21:10:05Z

`ruff-ecosystem` results

Linter (stable)

✅ ecosystem check detected no linter changes.

Linter (preview)

✅ ecosystem check detected no linter changes.

Formatter (stable)

✅ ecosystem check detected no format changes.

Formatter (preview)

✅ ecosystem check detected no format changes.

MichaReiser · 2026-07-21T07:42:45Z

    ----- stdout -----
    unformatted: File would be reformatted
-      --> CRATE_ROOT/resources/test/fixtures/unformatted.ipynb:cell 1:1:1
+      --> CRATE_ROOT/resources/test/fixtures/unformatted.ipynb:cell 1:2:1


@ntBre is this the format check bugfix that you wanted to look into?

I don't think so. The root cause of #24528 is failing to attach spans to syntax error diagnostics, not a rendering issue.

MichaReiser · 2026-07-21T13:07:14Z

 6 | class FormFeedIndent:
-7 |    def __init__(self, a=[]):
-  |                         ^^
+7 |   ␌ def __init__(self, a=[]):


epage · 2026-07-21T13:17:05Z

-    --> has_syntax_error.py:1:1
+     --> has_syntax_error.py:2:1
+      |
+    2 |
+      | ^



While more correct, this may degrade #24528

epage · 2026-07-21T13:18:01Z

 3 | elf:
 4 |     pass
-  |         ^ Syntax Error: Expected a statement
 5 | else:
+  | ^ Syntax Error: Expected a statement
 6 |     pass


The span is between the \n and e, so this is the more correct placement but unsure what the intended placement is

MichaReiser · 2026-07-21T13:48:54Z

I'm a bit confused by the changes in Bless added pipes and Bless removed pipes. It's not clear what's different between the pipes that were removed/added.

Overall, it might be helpful to give a short explanation for each of those blessed commits. E.g. why did the locations in Bless origin location changes. Were they incorrect, why? Same for added/removed pipes. Why were they removed/added? Were they incorrect?

MichaReiser · 2026-07-21T13:53:41Z

 info: This violates the Liskov Substitution Principle
 help: It is recommended for `__eq__` to work with arbitrary objects, for example:
-help
+help: 


This now renders with a trailing whitespace. Any chance we can avoid printing the whitespace if not followed by a text?

I would prefer to keep this as-is and instead open a follow up issue to switch this to using a Snippet to render it. If it is important enough to this PR, I could instead make that change before hand.

epage · 2026-07-21T13:54:26Z

I'm a bit confused by the changes in Bless added pipes and Bless removed pipes. It's not clear what's different between the pipes that were removed/added.

Overall, it might be helpful to give a short explanation for each of those blessed commits. E.g. why did the locations in Bless origin location changes. Were they incorrect, why? Same for added/removed pipes. Why were they removed/added? Were they incorrect?

Looking at it closer, it appears that the "added" commit just undoes some of the "removed" commit. I've squashed them.

MichaReiser · 2026-07-21T13:55:12Z

-        --> lib/module.py:1:1
+         --> lib/module.py:1:1
+          |
+        1 |


Hmm, I think this is some special casing that @ntBre introduced to prevent this. I don't remember why we did that. Is there another way of disabling rendering of the snippet (at a diagnostic level)?

Looks like we should call hide_snippet in places where we don't want to show an empty span.

I looked through each case

One is that the annotated line is empty

The rest are when a snippet is being shown for context but the source for that snippet is empty

In each case, I think this PR is doing the right thing in showing these snippets.

Two potential improvements that I think are reasonable to defer are

Showing an ␃ for empty spans at the end of a file

Showing a line of context before an error on an empty line

If there is a reason we should special case to hide empty lines, I would appreciate better understanding it

Hmm, I think this is some special casing that @ntBre introduced to prevent this. I don't remember why we did that.

Also, I dug through the history and changes, and didn't see what this was referring to.

Oh, you might mean the file-level stuff.

And looking closer, some of those look like they should be file level (go-to-definition for a module takes you to the module)

Oh, yeah, these file-level snippets are for an internal-only render to visualize IDE actions so it doesn't really matter.

MichaReiser · 2026-07-21T13:57:33Z

 7 |
-  | ^ Syntax Error: Expected a statement
 8 | a = 10
+  | ^ Syntax Error: Expected a statement


I'd have to take a look at the parser but this certainly is confusing now. Because this is the start of a statement.

This seems accurate for what span the parser picks. I'd be nice if we can use a more meaningful range (or omit this error all together, if it always follow another error). If you're interested, feel free to take a look at it. I otherwise suggest that we open a follow up issue for this.

We could also consider slihgtly changing the wording, if that helps

Wow, #27170 removed all but one of these

MichaReiser · 2026-07-21T14:07:14Z

Codex explained to me that the line changes were cases where the diagnostic incorrectly used the range of a secondary annotation. Whoops. Nice catch.

Yes. The old Ruff-vendored annotate-snippets renderer used the first annotation in the snippet, irrespective of whether it was primary:

MichaReiser · 2026-07-21T14:27:36Z

This looks great overall. Thank you

See 5bfffe1

See 78e5fe0

See 2b1d3c6

See ca8b193

See 84ba4ec

78e5fe0 implemented support for hiding severities from upstream annotate-snippets. Likely, this was just an implementation oversight upstream but the exact details of what it should look like upstream are TBD.

I believe the new rendered is collapsing the trailing padding line with the annotation line.

The origin line and column is now determined by the primary annotation.

Reasons - Primary now has precedence over context when overlapping - The primary now always has the same symbol, independent of level

The old renderer allowed the snipper to go past the term width.

The annotation is between the newline and the first character, so this is the more correct place to render it.

When to go past the end-of-line to represent the newline has changed. The two renderers diverged in their newline behavior and I tried to restore the old behavior as much as possible and I hit my timebox for getting this exactly right since this didn't seem the most important to get perfectly the same.

epage · 2026-07-28T16:57:01Z

I'm going to go ahead and merge and continue to iterate as this is conflict heavy. If someone has a concern with this, we can revert.

epage requested review from a team, BurntSushi, MichaReiser and dhruvmanila as code owners July 20, 2026 20:49

epage marked this pull request as draft July 20, 2026 20:49

epage force-pushed the update-annotate branch from 5fa50a5 to 7a252c7 Compare July 20, 2026 20:54

epage force-pushed the update-annotate branch from 7a252c7 to 18f44d1 Compare July 20, 2026 21:09

epage force-pushed the update-annotate branch 2 times, most recently from 5bfbeb6 to ddbb335 Compare July 20, 2026 21:31

MichaReiser reviewed Jul 21, 2026

View reviewed changes

epage commented Jul 21, 2026

View reviewed changes

MichaReiser reviewed Jul 21, 2026

View reviewed changes

epage force-pushed the update-annotate branch from ddbb335 to 5d641f1 Compare July 21, 2026 13:55

MichaReiser reviewed Jul 21, 2026

View reviewed changes

epage added 25 commits July 28, 2026 11:19

Re-implement Jupyter cell index

c616fe5

See 5bfffe1

Re-implement fixable mark

7f2ba63

See 78e5fe0

Test lineno_offset

a2db3f2

Re-implement lineno_offset

d3ff519

See 2b1d3c6

Re-implement anonymized lines in origins

a630681

See ca8b193

Re-implement custom cut indicator

2a69d2e

See 84ba4ec

Test no_name/id combos

37234dc

Match ruff's existing hidden severity behavior

b3dc852

78e5fe0 implemented support for hiding severities from upstream annotate-snippets. Likely, this was just an implementation oversight upstream but the exact details of what it should look like upstream are TBD.

Test newline issue

61a519a

Force old newline behavior

516aac5

Force old indentation behavior

a1ebaad

Force old fold(false) default

9301e1d

Force old multi-line header behavior

29446fa

Force simd feature on by default

b78869d

Bless more characters being substituted

32c46f1

Bless removed pipes

4b62395

I believe the new rendered is collapsing the trailing padding line with the annotation line.

Bless origin location changes

dc06cb1

The origin line and column is now determined by the primary annotation.

Bless underlining change

602a877

Reasons - Primary now has precedence over context when overlapping - The primary now always has the same symbol, independent of level

Bless trailing whitespace

4672619

Bless snippets always being rendered, even when empty

84a1b5e

Bless fixes for respecting term width

af581ae

The old renderer allowed the snipper to go past the term width.

Bless annotation location between newline and first character

b53c27a

The annotation is between the newline and the first character, so this is the more correct place to render it.

Bless new multi-line annotation markers

3f239d6

Bless blobs

5eec5d3

epage force-pushed the update-annotate branch from 9395226 to 5eec5d3 Compare July 28, 2026 16:26

epage merged commit 958efb1 into astral-sh:main Jul 28, 2026
63 checks passed

epage deleted the update-annotate branch July 28, 2026 16:57

BrewTestBot mentioned this pull request Jul 30, 2026

ruff 0.16.1 Homebrew/homebrew-core#296221

Merged

Uh oh!

Conversation

epage commented Jul 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test Plan

Uh oh!

astral-sh-bot Bot commented Jul 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

No changes detected ✅

Uh oh!

astral-sh-bot Bot commented Jul 20, 2026

Memory usage report

Uh oh!

astral-sh-bot Bot commented Jul 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

ecosystem-analyzer results

Uh oh!

astral-sh-bot Bot commented Jul 20, 2026

ruff-ecosystem results

Linter (stable)

Linter (preview)

Formatter (stable)

Formatter (preview)

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

MichaReiser commented Jul 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

epage commented Jul 21, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

MichaReiser Jul 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

MichaReiser commented Jul 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

MichaReiser commented Jul 21, 2026

Uh oh!

epage commented Jul 28, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

epage commented Jul 20, 2026 •

edited

Loading

astral-sh-bot Bot commented Jul 20, 2026 •

edited

Loading

astral-sh-bot Bot commented Jul 20, 2026 •

edited

Loading

`ecosystem-analyzer` results

`ruff-ecosystem` results

MichaReiser commented Jul 21, 2026 •

edited

Loading

MichaReiser Jul 21, 2026 •

edited

Loading

MichaReiser commented Jul 21, 2026 •

edited

Loading