[ty] report unreachable code as unnecessary hint diagnostics by denyszhak · Pull Request #24580 · astral-sh/ruff

denyszhak · 2026-04-13T00:13:53Z

Summary

Implements dimming for unreachable code in LSP-capable editors. Unreachable ranges are collected from the semantic index and emitted as DiagnosticTag::UNNECESSARY hints.

Test Plan

Unit tests coverage, e2e test coverage and manual testing

denyszhak · 2026-04-13T00:15:21Z

It's a draft for now with only two types of unreachable code but I need to think slightly more to map it to more precise types: structural, static, maybe type related before sending for review.

astral-sh-bot · 2026-04-13T21:58:15Z

Typing conformance results

No changes detected ✅

Current numbers

The percentage of diagnostics emitted that were expected errors held steady at 87.94%. The percentage of expected errors that received a diagnostic held steady at 83.36%. The number of fully passing files held steady at 79/133.

astral-sh-bot · 2026-04-13T21:59:01Z

Memory usage report

Memory usage unchanged ✅

astral-sh-bot · 2026-04-13T22:01:49Z

`ecosystem-analyzer` results

No diagnostic changes detected ✅

Full report with detailed diff (timing results)

denyszhak · 2026-04-14T22:30:12Z

It's a draft for now with only two types of unreachable code but I need to think slightly more to map it to more precise types: structural, static, maybe type related before sending for review.

I ended up keeping only two categories for now. Splitting further into structural/static/type-analysis-style categories is possible in principle, but with the current reachability plumbing that would require extra classification logic at this layer mainly to refine the user-facing message. The current implementation still covers the full set of unreachable cases, what’s intentionally deferred is finer-grained messaging. I didn’t want to add more categorization logic unless we can align it with ty’s actual reachability model rather than approximate pyright’s labels.

MichaReiser

This is very cool. Thank you for working on it.

I only have a few suggestions around wording, documentation, and test structure. This is otherwise good to go.

MichaReiser · 2026-04-15T12:50:11Z

+                "Code is unreachable".to_owned()
+            }
+            Self::UnreachableCode(UnreachableKind::CurrentAnalysis) => {
+                "Code is unreachable under the current analysis".to_owned()


I think I'd go with Code is unreachable for this project’s configured settings

Yes this is better, I didn't have a good name but didn't like the one I came up with and I knew you would have a good suggestion, thanks!

I think I need to first think about David's suggestion below so that this statement will be true in reality.

Based on the discussion below, mentioning project settings for the CurrentAnalysis bucket would be misleading, since some of those cases are not settings-driven. For settings cases, it would be better to add a separate Configuration category for the patterns ty can reliably distinguish today. I can take a look at that either in this PR or as a follow up after analyzing what those patterns are.

Co-authored-by: Micha Reiser <micha@reiser.io>

…de.rs Co-authored-by: Micha Reiser <micha@reiser.io>

sharkdp · 2026-04-15T15:14:03Z

+                        kind: if constraint == ScopedReachabilityConstraintId::ALWAYS_FALSE {
+                            UnreachableKind::Unconditional
+                        } else {
+                            UnreachableKind::CurrentAnalysis
+                        },


Only certain simple patterns like if False have a constraint of ALWAYS_FALSE. There are more complex patterns like if 1 + 1 == 3 or if isinstance("test", str) which need type inference for evaluation. It looks like we are categorizing these as CurrentAnalysis here.

I have not reviewed the rest of the code, so maybe this is not problematic. But it might be slightly confusing for users?

(I was always expecting that we would have to do the opposite to achieve this categorization: to match on a restricted set of patterns like if sys.version_info >= (3, 10) which we would know depend on the current user settings; and then categorize everything else as Unconditional)

What you say is to flip this thing to have like two types of unreachable: Configuration and Unconditional and we have let's say is_configuration_expr and everything that evaluate as config goes into this bucket and everything else is Unconditional?

This sounds good actually, I was slightly confused in what separate would be best.

I think this is actually the correct way for UX, I will update this

Yes. It would be good to understand which of these failure cases is more problematic:

an "unconditionally unreachable" statement that is falsely being labeled as "unreachable due to config settings"

a statement that is "unreachable due to config settings" that is falsely being labeled as "unconditionally unreachable"

We should probably answer that before we make any changes here.

Second one sounds worse for me. Labeling config-dependent code as unconditionally unreachable would be a stronger claim than we can justify, since that code may still be reachable on another Python version or platform. The other direction is still a loss of precision, but less misleading. So I think the safer approach is to keep the configuration bucket narrow and only use for explicitly recognized config patterns, and make the fallback bucket the regular generic unreachable case rather than “unconditional”.

wdyt?

I agree with this. The thing we will surface to users is the claim that some code is (always) unreachable (implied: you may as well delete it.) False positives in this identification are worse than false negatives.

I think the current version is in a good state to merge as-is. It already covers the unreachable ranges correctly. If we were to refine the split, I think the safer shape is Configuration for explicitly recognized patterns, Unconditional for ALWAYS_FALSE, and CurrentAnalysis as the fallback (maybe improve the wording for this one now).

I could work on that either in this PR or in a follow-up, after analyzing which patterns ty can classify reliably today.

sharkdp · 2026-04-15T15:20:08Z

+        let snippets = collect_unreachable_entries(&db, "/src/main.py", &source);
+        assert_eq!(
+            snippets,
+            vec![(
+                "if False:\n        x = lambda: 1".to_owned(),
+                UnreachableKind::CurrentAnalysis
+            )]
+        );


This is interesting. Should this have a TODO comment maybe that this could be even better, in principle? The if False: is of kind CurrentAnalysis, but the x = lambda: 1 could be of the (stronger) unreachable kind Unconditional, right?

Yeah, good point! x = lambda: 1 is Unconditional on its own, but the merged span also includes if False: and that line is only dead under the current analysis. So CurrentAnalysis looks as the correct kind for the whole merged span, not a limitation. Happy to add a comment to the test clarifying this if useful.

As for reporting two separate ranges - I'm not sure that would be better UX either, since you will end up with two overlapping dim regions for the same code.

astral-sh-bot bot added the ty Multi-file analysis & type inference label Apr 13, 2026

denyszhak changed the title ~~Feat/unreachable code hints~~ [ty] report unreachable code as unnecessary hint diagnostics Apr 13, 2026

AlexWaygood added the server Related to the LSP server label Apr 13, 2026

denyszhak added 2 commits April 13, 2026 23:02

[ty]: gray out unreachable code

bbf8828

[ty]: replace bare strings at the collection phase with enum

0ff2771

denyszhak force-pushed the feat/unreachable-code-hints branch from 2588537 to 3013807 Compare April 13, 2026 21:56

[ty] report two different types of unreachable code

23e75da

denyszhak force-pushed the feat/unreachable-code-hints branch from 3013807 to 23e75da Compare April 13, 2026 22:59

[ty] remove good chunk of redundant code

512cf2b

denyszhak marked this pull request as ready for review April 14, 2026 22:32

denyszhak requested review from AlexWaygood, BurntSushi, Gankra, MichaReiser, carljm, dcreager, ibraheemdev and sharkdp as code owners April 14, 2026 22:32

astral-sh-bot bot assigned dhruvmanila Apr 14, 2026

astral-sh-bot bot requested a review from dhruvmanila April 14, 2026 22:32

MichaReiser approved these changes Apr 15, 2026

View reviewed changes

denyszhak and others added 2 commits April 15, 2026 16:09

Apply suggestion from @MichaReiser

908b326

Co-authored-by: Micha Reiser <micha@reiser.io>

Update crates/ty_python_semantic/src/types/ide_support/unreachable_co…

47b7de7

…de.rs Co-authored-by: Micha Reiser <micha@reiser.io>

sharkdp reviewed Apr 15, 2026

View reviewed changes

Comment thread crates/ty_python_semantic/src/types/ide_support/unreachable_code.rs Outdated

sharkdp reviewed Apr 15, 2026

View reviewed changes

AlexWaygood removed their request for review April 15, 2026 15:33

[ty] fixes per feedback

c4b35c1

denyszhak force-pushed the feat/unreachable-code-hints branch from de32cae to e5ee50a Compare April 15, 2026 17:26

[ty] needless borrow

e53946c

denyszhak force-pushed the feat/unreachable-code-hints branch from e5ee50a to e53946c Compare April 15, 2026 17:50

Conversation

denyszhak commented Apr 13, 2026

Summary

Test Plan

Uh oh!

denyszhak commented Apr 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

astral-sh-bot bot commented Apr 13, 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 Apr 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Memory usage report

Uh oh!

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

Uh oh!

ecosystem-analyzer results

Uh oh!

denyszhak commented Apr 14, 2026

Uh oh!

MichaReiser left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

denyszhak Apr 15, 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

denyszhak Apr 15, 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!

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!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

denyszhak Apr 15, 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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

denyszhak commented Apr 13, 2026 •

edited

Loading

astral-sh-bot bot commented Apr 13, 2026 •

edited

Loading

astral-sh-bot bot commented Apr 13, 2026 •

edited

Loading

astral-sh-bot bot commented Apr 13, 2026 •

edited

Loading

`ecosystem-analyzer` results

denyszhak Apr 15, 2026 •

edited

Loading

denyszhak Apr 15, 2026 •

edited

Loading

denyszhak Apr 15, 2026 •

edited

Loading