Dim the code that cannot be reached

[petrovo-as]

Note

I am not a Rust developer. This was written with AI assistance and reviewed line by line, including two rounds of adversarial review that between them caught two false positives around goto: one where a jump was treated as leaving the block it stayed inside, and one where a return the jump skipped over dimmed the live code after that block. Please read it as a proposal rather than as finished work.

The problem

A statement after one that always leaves the block never runs, and nothing said so. This is D6 in the backlog, which the change implements and removes.

The change

return, throw, exit, die, continue, break, and an if whose every branch does one of those all end a block. An if without an else never does, since a path through it always falls through.

Reported as a Hint tagged Unnecessary, per D6, so editors grey the text out rather than underlining it. The check reads the shape of the statement list and nothing else, which keeps it in the fast phase.

Two things only look dead. A declaration at the top level of a file is hoisted and holds wherever it sits, while the same declaration inside a function body is created by running the statement and after a return never comes into being — they are told apart by where they sit, not by what they are. A goto label is an entry point that ends the dead run. Either can sit in the middle of otherwise dead code, so one block may hold several runs, each reported on its own.

Not included

A call to a function declared never also ends a block. Recognising it needs the type engine, which would move the check into the expensive phase to catch a case the reader can already see.

Two gaps are filed rather than fixed, as D24 and D25: the "Remove unreachable code" action reads PHPStan's diagnostics only and deletes to the next closing brace instead of using the reported range, so wiring the native code to it needs more than adding the code; and a braced namespace or declare body is treated as a fresh statement list, so reachability neither flows in nor out.

Testing

36 integration tests in diagnostics_unreachable_code.rs, asserting on the text that was dimmed rather than on line numbers. Demos added to examples/php/diagnostics.php. Full suite, clippy --all-targets -D warnings, and fmt --check pass.

Checklist

If applicable:

• I have updated CHANGELOG.md
• I have updated the documentation (README.md, docs/, examples/)
• I have updated the config schema (config-schema.json)
• I have added/updated tests to cover my changes
• I fully understand the code that I am submitting (what it does,
  how it works, how it's organized), including any code drafted by an LLM.
• For any prose generated by an LLM, I have proof-read and copy-edited with
  an eye towards deleting anything that is irrelevant, clarifying anything
  that is confusing, and adding details that are relevant. This includes,
  for example, commit descriptions, PR descriptions, and code comments.

🤖 Generated with Claude Code

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

❌ Patch coverage is 98.19005% with 4 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/diagnostics/unreachable_code.rs	98.17%	4 Missing ⚠️

📢 Thoughts on this report? Let us know!