C0005 panic-in-library¶
Rule: Library code returns errors for what can fail and says why where it panics.
| Code | C0005 (stable, never reused) |
| Id | panic-in-library |
| Category | code |
| Source | spirit_level |
| Fix | by hand |
Level per tier¶
| Tier | Level | Reason |
|---|---|---|
| small | off | |
| small-workspace | off | |
| medium | warn |
a library returns errors for what can fail and says why where it panics; warn until tpm_cli, wire_weaver and embedded_bedrock are under 50 findings each, then deny |
| big | warn |
a library returns errors for what can fail and says why where it panics; warn until tpm_cli, wire_weaver and embedded_bedrock are under 50 findings each, then deny |
| ai | off | |
| embedded | deny |
a service module (LED, log, telemetry) never reaches the panic handler in release: the whole MCU resets for it |
| ui | off | |
| egui | off | |
| units-strict | off | |
| units-paranoid | off |
Parameters¶
| Name | Type | Default | Meaning |
|---|---|---|---|
methods |
list of strings | ["unwrap"] |
methods that panic on None or Err without saying why |
macros |
list of strings | ["panic", "todo", "unimplemented"] |
macros that panic |
bare-macros |
list of strings | ["unreachable"] |
macros that count only without a message |
test-files |
list of strings | ["**/*_tests.rs"] |
files of test code by name, relative to the crate, besides tests/, benches/, examples/ and #[cfg(test)] modules |
classes |
list of strings | [] |
task classes ([embedded.classes]) whose modules are checked in every crate, binaries included, instead of library code |
max |
integer | 0 |
panicking calls allowed per crate before each is reported |
Why¶
A library that panics where something can fail takes its caller down: a server, a GUI, an agent's long run. An error of operation (a value from outside, I/O, a peer) is a Result the caller decides about. A broken invariant is a panic, and the panic says why the case cannot happen:
| Written | Counted |
|---|---|
.unwrap() |
yes: it says nothing about why it cannot fail |
.expect("8 bytes sliced") |
no: the reason is read at the site |
panic!, todo!, unimplemented! |
yes |
unreachable!() |
yes |
unreachable!("handled before load") |
no |
assert!(cond, "message") |
no: an invariant check (see assert-message, compound-assert) |
Binaries (src/main.rs, src/bin/) and test code are not checked: tests/, benches/, examples/, #[cfg(test)] modules and items, and files named like test code (test-files, *_tests.rs by default). .lock().unwrap() is left to lock-unwrap: a poisoned lock panics on purpose.
Without types, .unwrap() on anything counts, including types where it cannot panic in practice; the parameter max sets how many a crate may have before each is reported.
In firmware the module's task class decides, not the crate kind. The embedded tier sets classes = ["service"]: every module that [embedded.classes] puts in service is checked, in binaries too, with expect, unreachable! and assert! counted as well, since a service module never reaches the panic handler in release.
How to fix¶
- A value from outside or an operation that can fail: return an error the caller can handle.
- A case that cannot happen:
.expect("why it cannot fail")orunreachable!("why"); better, a type that makes it impossible (NonZeroU8, an enum, a checked constructor). - In a
servicemodule:debug_assert!, count the miss (cnt!) and fall back (skip the sample, clamp, reset the task's own state).
Configure¶
[lints.panic-in-library]
level = "deny"
methods = ["unwrap"]
macros = ["panic", "todo", "unimplemented"]
bare-macros = ["unreachable"]
test-files = ["**/*_tests.rs"]
classes = []
max = 0
reason = "why this project wants it at this level"
Allow one finding in the code with // spirit-level: allow(panic-in-library) <reason> (waivers); the code works there too, as in [lints.C0005].