Improve linter's diagnostics when it ICEs

[BD103]

Objective

When the linter panics (also known as an Internal Compiler Error, ICE), its output is difficult to read. There's no colors, and it looks like a giant wall of text!

Example ICE

thread 'rustc' panicked at bevy_lint/src/lints/pedantic/borrowed_reborrowable.rs:152:9:
assertion `left == right` failed: there must be the same number of argument types and parameters
  left: 1
 right: 0
stack backtrace:
   0:        0x112eb7a38 - <std::sys::backtrace::BacktraceLock::print::DisplayBacktrace as core::fmt::Display>::fmt::hae40585d89eb05f9
   1:        0x1104a6940 - core::fmt::write::h5f993f0cf8d2277d
   2:        0x112eac36c - std::io::Write::write_fmt::h1d1ea9b540b61f44
   3:        0x112eb78f8 - std::sys::backtrace::BacktraceLock::print::h7fd3f45e007ba498
   4:        0x112ebc5b4 - std::panicking::default_hook::{{closure}}::hbf1b04bb4da5c296
   5:        0x112ebc284 - std::panicking::default_hook::h9178e4d12ab72538
   6:        0x111015840 - std[74a5b01c11208b85]::panicking::update_hook::<alloc[d26ef1a2a5bec82e]::boxed::Box<rustc_driver_impl[4174c532cc880436]::install_ice_hook::{closure#1}>>::{closure#0}
   7:        0x112ebcf9c - std::panicking::rust_panic_with_hook::h88b475da2a179ab7
   8:        0x112ebcb90 - std::panicking::begin_panic_handler::{{closure}}::h5ac0760c79d332ac
   9:        0x112eb7ed0 - std::sys::backtrace::__rust_end_short_backtrace::h05b5dbe6d5998bca
  10:        0x112ebc858 - __rustc[bf3627c2b8b7eae9]::rust_begin_unwind
  11:        0x115af71ac - core::panicking::panic_fmt::h851abc9cfd369761
  12:        0x115af757c - core::panicking::assert_failed_inner::h8e189ce54df144a5
  13:        0x115af7498 - core::panicking::assert_failed::h10131ad6f90a3576
  14:        0x104b8f5c8 - <bevy_lint::lints::pedantic::borrowed_reborrowable::BorrowedReborrowable as rustc_lint::passes::LateLintPass>::check_fn::h921e11df1045f24a
                               at bevy_lint/src/lints/pedantic/borrowed_reborrowable.rs:152:9
  15:        0x111a0be78 - <rustc_lint[824693d4afadf9eb]::late::LateContextAndPass<rustc_lint[824693d4afadf9eb]::late::RuntimeCombinedLateLintPass>>::with_param_env::<<rustc_lint[824693d4afadf9eb]::late::LateContextAndPass<rustc_lint[824693d4afadf9eb]::late::RuntimeCombinedLateLintPass> as rustc_hir[da443efb3d4b762a]::intravisit::Visitor>::visit_item::{closure#0}::{closure#0}>
  16:        0x111949910 - rustc_hir[da443efb3d4b762a]::intravisit::walk_mod::<rustc_lint[824693d4afadf9eb]::late::LateContextAndPass<rustc_lint[824693d4afadf9eb]::late::RuntimeCombinedLateLintPass>>
  17:        0x111a119c8 - rustc_lint[824693d4afadf9eb]::late::check_crate::{closure#0}
  18:        0x111a11000 - rustc_lint[824693d4afadf9eb]::late::check_crate
  19:        0x1118ff68c - rustc_interface[d4e94194bc4ed16]::passes::analysis
  20:        0x11261484c - rustc_query_impl[2935a623bbe6cc1f]::plumbing::__rust_begin_short_backtrace::<rustc_query_impl[2935a623bbe6cc1f]::query_impl::analysis::dynamic_query::{closure#2}::{closure#0}, rustc_middle[b3454187f9b0105e]::query::erase::Erased<[u8; 0usize]>>
  21:        0x1123e66f0 - rustc_query_system[c1558d495c82de46]::query::plumbing::try_execute_query::<rustc_query_impl[2935a623bbe6cc1f]::DynamicConfig<rustc_query_system[c1558d495c82de46]::query::caches::SingleCache<rustc_middle[b3454187f9b0105e]::query::erase::Erased<[u8; 0usize]>>, false, false, false>, rustc_query_impl[2935a623bbe6cc1f]::plumbing::QueryCtxt, true>
  22:        0x112620990 - rustc_query_impl[2935a623bbe6cc1f]::query_impl::analysis::get_query_incr::__rust_end_short_backtrace
  23:        0x110fc626c - rustc_interface[d4e94194bc4ed16]::passes::create_and_enter_global_ctxt::<core[108b704551f1b2c6]::option::Option<rustc_interface[d4e94194bc4ed16]::queries::Linker>, rustc_driver_impl[4174c532cc880436]::run_compiler::{closure#0}::{closure#2}>
  24:        0x11101263c - rustc_interface[d4e94194bc4ed16]::interface::run_compiler::<(), rustc_driver_impl[4174c532cc880436]::run_compiler::{closure#0}>::{closure#1}
  25:        0x111003594 - std[74a5b01c11208b85]::sys::backtrace::__rust_begin_short_backtrace::<rustc_interface[d4e94194bc4ed16]::util::run_in_thread_with_globals<rustc_interface[d4e94194bc4ed16]::util::run_in_thread_pool_with_globals<rustc_interface[d4e94194bc4ed16]::interface::run_compiler<(), rustc_driver_impl[4174c532cc880436]::run_compiler::{closure#0}>::{closure#1}, ()>::{closure#0}, ()>::{closure#0}::{closure#0}, ()>
  26:        0x111018ffc - <<std[74a5b01c11208b85]::thread::Builder>::spawn_unchecked_<rustc_interface[d4e94194bc4ed16]::util::run_in_thread_with_globals<rustc_interface[d4e94194bc4ed16]::util::run_in_thread_pool_with_globals<rustc_interface[d4e94194bc4ed16]::interface::run_compiler<(), rustc_driver_impl[4174c532cc880436]::run_compiler::{closure#0}>::{closure#1}, ()>::{closure#0}, ()>::{closure#0}::{closure#0}, ()>::{closure#1} as core[108b704551f1b2c6]::ops::function::FnOnce<()>>::call_once::{shim:vtable#0}
  27:        0x112ebf4e0 - std::sys::pal::unix::thread::Thread::new::thread_start::hfbd86c07930dd987
  28:        0x18677ec0c - __pthread_cond_wait

error: the compiler unexpectedly panicked. this is a bug.

note: we would appreciate a bug report: https://github.com/TheBevyFlock/bevy_cli/issues

note: please make sure that you have updated to the latest nightly

note: please attach the file at `rustc-ice-2025-07-12T14_37_56-59122.txt` to your bug report

note: compiler flags: --crate-type bin -C embed-bitcode=no -C incremental=[REDACTED]

note: some of the compiler flags provided by cargo are hidden

query stack during panic:
#0 [analysis] running analysis passes on this crate
end of query stack
note: This is likely a bug with `bevy_lint`, not `rustc` or `cargo`.

Additionally, we currently don't have a convention for when panicking is suitable, and when silently skipping errors should be done instead.

Solution

• Write a new page in the Contributor's Guide on panicking.
  • Switch some debug_assert! calls to normal assert! calls for cases where the check is very cheap. This will help us catch bugs!
• Create custom macros that use rustc's diagnostics to emit errors.
  • These macros support emitting to a Span, which helps diagnose issues.
  • Switch to these custom macros, emitting to a Span wherever possible.

Showcase

Before:

After:

After (emitting with a Span):

[BD103]

I'm marking this as blocked. Although it can technically be reviewed, I think we should hold off merging this until v0.4.0 is released.