External tools¶
spirit_level reuses established Rust lint tools instead of reimplementing them. Each tool sits behind an adapter: an analysis like any other, whose lints carry the tool's prefix (clippy-, deny-, machete-, ...) and are configured, overridden, excepted and waived in spirit_level.toml like native ones.
How tools are run¶
- Library or executable. A tool with a library on stable Rust that does the whole job is linked in, always compiled; it runs only when one of its lints is on. The others run as executables, and the adapter reads their machine-readable output (JSON where the tool has it, its stable text where not).
- Found on PATH. spl installs nothing. Each tool is found on PATH and its version read, so it comes from whatever installs tools here:
cargo binstall,cargo install, a distribution's package, mise. - Missing tools. A lint whose executable is not installed is reported as not run with the reason and the
crate@versionthat installs it. The run then exits with code 3, atwarnas atdeny(exit codes). - Tested versions.
crates/sl_tools/tools.tomlgives each tool the range of versions its parser is tested against. A tool outside that range still runs;tool-version(deny from the small tier) reports its results as untested and fails the run. - What a project needs.
spl tools neededlists what the project's enabled lints need: their tools, the toolchain of eachrust-versionforcargo-msrv, and the targets ofcargo-no-stdandcargo-wasmwhen the map marks crates. Install them beforecheckin CI, so no lint is left not run.
Library or executable¶
Cost of linking: a scratch project depending only on the library (default-features = false), built cold with cargo build --release -j 4. Crates are the unique packages in cargo tree -e normal,build. C is any -sys crate with a native build, cc, cmake, ring or aws-lc-sys in that tree. For scale, spirit_level's own base (cargo_metadata, toml_edit, syn, serde_json) is 26 crates and 12 s.
| Tool | Used as | Why | Cost of linking (crates, s, C) |
|---|---|---|---|
| clippy | executable | its lints are rustc plugins: rustc_private, nightly only |
not linkable on stable |
| rustfmt | executable | rustfmt_nightly is rustc_private too |
not linkable on stable |
| cargo-deny | executable | the library pulls C into every build, for checks that run once per CI job | 143, 63 s, ring, zstd-sys |
| cargo-audit (rustsec) | executable | fetching the advisory database needs the default features, which build C | 249, 97 s, aws-lc-sys, cmake; without fetch 54, 11 s |
| cargo-machete | executable | binary only, no library target | none |
| cargo-shear | executable | its library does not build with a fresh lock (ra-ap-rustc_lexer) | 120 crates, fails to build |
| typos | executable | the typos library is only the tokenizer; config, file walk and ignore rules live in typos-cli |
typos + dict 22, 14 s; typos-cli 129, 37 s |
| taplo | executable | the config and file-walk layer (taplo-common) needs a tokio runtime | taplo 53, 16 s; taplo-common 158, 41 s |
| cargo-semver-checks | executable | heavy, builds C, and its library report has no per-check detail | 308, 115 s, ring |
| cargo-udeps | executable | needs nightly, and links cargo itself (libgit2, curl) | not linkable on stable |
| hakari | library | guppy and hakari are libraries first; no C | 86, 20 s, none |
| geiger | library | a small library that counts unsafe with syn |
41, 11 s, none |
Lint mapping¶
A tool's findings map to spirit_level lints in one of two ways, chosen so that a level, an exception or an expiry in spirit_level.toml means something:
- One lint per family. When the tool sorts its findings into a few groups a project sets apart (clippy's groups, cargo-deny's checks, cargo-audit's kinds), each group is a lint.
- One lint per tool. When every finding is the same kind of problem (an unused dependency, a misspelling, an unformatted file), the tool is one lint.
In both cases the item (the fingerprint waivers and baselines use) carries the tool's own code: clippy::needless_range_loop@src/lib.rs:for i in 0..n, licenses:unlicensed:foo@1.0.0. Which of a tool's own checks run stays the tool's configuration ([lints.clippy], deny.toml, _typos.toml, taplo.toml); spirit_level decides how much a finding weighs.
clippy¶
- Command:
cargo clippy --message-format jsonplus theargsparameter ofclippy-build(default--workspace --all-targets). The groups come fromclippy-driver -W help. - Output: cargo's JSON messages;
compiler-messageobjects carry the rustc diagnostic with itscode(clippy::lint_name) and spans. - Exit codes: 0 built (warnings included), 101 a build error. Findings come from the messages, not the code.
- Lints:
clippy-correctness,-suspicious,-style,-complexity,-perf,-pedantic,-nursery,-cargo,-restrictionby group;clippy-buildfor rustc's own warnings and errors. No-Wflags are passed, so the project's[lints.clippy]decides what runs.
rustfmt¶
- Command:
cargo fmt --all --check --message-format short. - Output: one absolute path per line for each file rustfmt would change; parse errors on stderr.
- Exit codes: 0 formatted, 1 a file to change or a parse error.
- Lints:
rustfmt-unformatted, one finding per file.
cargo-deny¶
- Command:
cargo deny --format json --color never check <check>, once per enabled check;--offlinewhen thefetchparameter is false. - Output: JSON lines on stderr.
"type": "diagnostic"objects carrycode,severity,message,labelsandgraphs(the crate and the chain that pulls it in);"type": "log"objects are cargo-deny's log. - Exit codes: a bit set of the failed checks: 1 advisories, 2 bans, 4 licenses, 8 sources. A failure without diagnostics is a failed run (
run:cargo-deny). - Lints:
deny-advisories,deny-bans,deny-licenses,deny-sources.deny-advisoriesworks without adeny.toml; the others need the project's lists in it.
cargo-audit¶
- Command:
cargo audit --json, with--no-fetchwhen thefetchparameter is false. - Output: one JSON document:
vulnerabilities.list(each withadvisory,versions,package) andwarnings, a map from kind (unmaintained,unsound,yanked) to the same shape. - Exit codes: 0 no vulnerability, 1 a vulnerability; errors on stderr.
- Lints:
audit-vulnerabilities,audit-unmaintained,audit-unsound,audit-yanked. It overlapsdeny-advisories; a project uses one of them.
cargo-machete¶
- Command:
cargo machete --skip-target-dir . - Output: per crate with unused dependencies a line
<crate> -- <path>/Cargo.toml:, then one tab-indented line per dependency. - Exit codes: 0 none, 1 found some, 2 an error.
- Lints:
machete-unused-deps, one finding per crate and dependency. A false positive goes into the crate's[package.metadata.cargo-machete] ignored.
cargo-shear¶
- Command:
cargo shear --format json --color never. - Output: one JSON document:
summaryandfindings, each with acode(shear/unused_dependency,shear/misplaced_dependency, ...),severity,message,fileand a bytelocation. - Exit codes: 0 none, 1 found some, 2 an error.
- Lints:
shear-unused-deps(also unused workspace dependencies),shear-misplaced-deps(a dependency only tests use). An alternative to cargo-machete that also sees misplaced dependencies.
typos¶
- Command:
typos --format jsonin the project root. - Output: JSON lines;
"type": "typo"objects carrypath,line_num,byte_offsetin the line,typoandcorrections. It readstypos.toml(_typos.toml,.typos.toml) and.gitignore. - Exit codes: 0 clean, 2 typos found, others an error.
- Lints:
typos-misspelling, one finding per place; an exact fix when typos offers one correction.
taplo¶
- Command:
taplo fmt --check --colors neveron the TOML filesgit ls-fileslists (taplo's own walk enters ignored directories). The fix istaplo fmt --stdin-filepath <file> -, sotaplo.toml's per-path rules apply. - Output: log lines; an unformatted file is
ERROR taplo:format_files: the file is not properly formatted path="<path>", a parse error anerror: invalid TOMLreport with a┌─ <path>:<line>:<column>line. - Exit codes: 0 clean, 1 a file not formatted or not parsing.
- Lints:
taplo-fmt, one finding per file, with an exact fix.
cargo-semver-checks¶
- Command:
cargo semver-checks -p <crate> --color neverfor each crate the map marksstable = true(or thepackagesparameter);--baseline-revor--baseline-rootfrom the parameters, else the latest release on crates.io. - Output: text only. Each failed check is a line
--- failure <check>: <what> ---, its places follow underFailed in:(<item> in <file>:<line>), and aSummaryline names the bump the changes need. - Exit codes: 0 the version bump covers every change, 1 otherwise.
- Lints:
semver-checks-breaking, one finding per check and place; the item carries the check's name.
cargo-udeps¶
- Command:
cargo +nightly udeps --output json --workspace --all-targets. - Output: one JSON document:
successandunused_deps, a map from package id to itsmanifest_pathand unusednormal,developmentandbuilddependencies. - Exit codes: 0 none, 1 found some or a failed build (stderr).
- Lints:
udeps-unused-deps. It needs a nightly toolchain; without one the lint is not run.
hakari (linked)¶
- Library: guppy reads the full
cargo metadata; hakari computes the workspace-hack from.config/hakari.toml(or.guppy/hakari.toml), ascargo hakaridoes. - Equivalent commands:
cargo hakari generate --diffandcargo hakari manage-deps --dry-run. - Lints:
hakari-generate(the generated section of the workspace-hack'sCargo.tomlis current; exact fix writes it) andhakari-manage-deps(every managed member depends on the workspace-hack, and no other crate does). Always linked in.
geiger (linked)¶
- Library: every package the members reach through normal and build edges is scanned, each
.rsfile outside tests parsed with syn. A package whose library root says#![forbid(unsafe_code)]and counts nothing is skipped. - Lints:
geiger-unsafe-deps, one finding per dependency with more unsafe uses thanmax-usesthat is not inallow. Always linked in.
Cargo checks¶
Builds that cargo does itself, reported from --message-format json. Other toolchains and targets build into target/spirit-level/<check>/, so they never invalidate the normal build. A toolchain or target that is not installed makes the lint not run, with the rustup command that adds it; rustup is never allowed to install one by itself.
cargo-msrv:cargo checkwith the toolchain of each crate'srust-version, per version.cargo-no-std:cargo check -p <crate> --target <t> --no-default-featuresfor each crate the map marksno_std = true, on each of thetargets(defaultthumbv7em-none-eabihf);argsreplaces--no-default-features.cargo-wasm:cargo check -p <crate> --target wasm32-unknown-unknownfor each crate the map markswasm = true.cargo-doc:cargo doc; every rustdoc warning is a finding, asRUSTDOCFLAGS=-D warningswould fail.
Installing the tools¶
spl tools needed shows each tool the project needs: its tested range, the version found and where, whether it is in range, whether it runs on nightly, a later PATH entry that already has it in range, and the lints that run it. It exits with 1 while something needed is missing or outside its tested range. Its other outputs feed an installer:
| Flag | Prints | For |
|---|---|---|
--spec |
one crate@version per line |
xargs -r cargo binstall -y, xargs -r -n1 cargo install --locked |
--components |
one rustup component per line | xargs -r rustup component add |
--toolchains |
one toolchain per line (cargo-msrv) |
xargs -r -n1 rustup toolchain install --profile minimal |
--targets |
one target per line (cargo-no-std, cargo-wasm) |
xargs -r rustup target add |
--json |
every record: crate, version, tested range, path, version found, state, shadow, lints | scripts and packagers |
--missing keeps only what is missing, outside its tested range or prints no version. --all lists every tool that has an adapter, without reading a project. For example, in CI:
spl tools needed --spec --missing | xargs -r cargo binstall -y
spl tools needed --components --missing | xargs -r rustup component add
spl check
The version in --spec is the one the parser is tested at. A tool's version is the first word shaped like one in the output of its version-args (default --version); cargo-udeps runs on a nightly toolchain, which rustup toolchain install nightly --profile minimal adds.
A tool shadowed on PATH¶
PATH is searched in order, and the first match wins. An earlier directory holding an out-of-range copy (a distribution package ahead of ~/.cargo/bin) hides an in-range one further down: --spec and --components never list such a tool, since installing it again changes nothing. The table's shadowed by column, the JSON shadow field and the tool-version finding's help all name the later path and version instead, and say to remove the earlier one from PATH or move its directory after the later one's.