Module diagnostics

Expand description

Hard-coded and user-controlled diagnostics

Diagnostics are user messages, like warnings and errors. When they are named for setting a user-overridable level, they are called lints.

§When should a diagnostic be a lint

Lints are generally preferred because of the level of control for users.

Use a hard-coded diagnostic when:

Critical errors
There is no associated package or workspace. The diagnostic must still be suppressible somehow (e.g. a user explicitly opting in to a config field’s default value)
The warning message is too important to allow a user to hide (rare)

The mechanics of adding a diagnostic is dependent on the requirements:

TOML syntax or manifest schema: passes::emit_parse_diagnostics, rules::PARSE_PASS_RULES
Lockfile
- May be overly broad for what dependencies are checked
Pre-build unit graph
- Tailored to a specific configuration (features, targets) but requires users to enumerate every configuration
Post-build unit graph: rules::unused_dependencies::lint_build_results
- Slow feedback cycle since a build needs to happen
Does not fit into any idea of a pass: directly call [cargo_util_terminal::Shell::warn] or crate::CargoResult::Err

When evaluating a diagnostic:

Only evaluate and emit for local packages unless it is for a future-incompat lint

When generating a diagnostic [report][cargo_util_terminal::report::Report]:

Try to keep the report succinct while ensuring a beginner can understand what is wrong and how to fix. It is a difficult balance to hit; err on the side of providing extra information.
Messages should generally be a phrase, starting with a lowercase letter. If multiple sentences are needed, consider if a [message][cargo_util_terminal::report::Message] or sub-diagnostic would be more appropriate.
Only the first lint for a package should emit the lint::Lint::emitted_source

When a diagnostic requires adding a new pass, keep in mind:

Support for build.warnings
When errors should block further evaluation within the pass
Providing a summary at the end, like what is provided by ScopedDiagnosticStats::report_summary
Prefer data driven passes to simplify adding rules
- Ensure the pass’ lints are in rules::LINTS, e.g. ensure_parse_passed_in_lints
- Prefer evaluating the lint level within the pass