The model
Five pieces, and the surface fits in your head:
- A
Ruleis one check: a stablename, adefault_level, and acheckthat inspects one node and reports problems. - A
Level—Allow,Warn, orDeny— is how strictly a rule is applied.Allowturns a rule off entirely; it is never called. - A
Linterholds the registered rules and their levels, and runs them all over a tree in one walk. - A
Contextis what a rule sees at each node: the arena, the node's ancestors and depth, and thereportcall. - A
Findingis one reported problem: adiag-langdiagnostic tagged with the rule that produced it.
Configuration errors — a duplicate rule name, a level set on a rule that does not exist, a level string that does not parse — are returned as a LintError at setup time. Running a configured linter never fails.
Installation
[]
= "1"
Or from the terminal:
MSRV: Rust 1.85 (Rust 2024 edition).
Quick start
An expression type, one rule that flags --x, and a linter that runs it. The user can escalate the rule to an error or switch it off.
use ;
;
// `--5`
let mut arena = new;
let five = arena.alloc;
let neg = arena.alloc;
let root = arena.alloc;
let mut linter = new;
linter.register?;
let findings = linter.run;
assert_eq!;
assert_eq!;
// Configuration is per rule, by name.
linter.set_level?;
assert!;
# Ok::
Rendering findings
Every finding carries a diag-lang diagnostic. Register the source in a SourceMap and render it for a caret-underlined report:
use ;
use ;
;
;
let source = "let x = TODO;";
let mut arena = new;
let root = arena.alloc;
let mut linter = new;
linter.register?;
let mut map = new;
let _file = map.add.expect;
let report = new.render;
assert!;
# Ok::
Configuration from text
Level parses from allow / warn / deny (ignoring ASCII case), so applying a configuration file or a command-line flag is a loop over set_level. Typos are errors, not silent no-ops:
use ;
# use ;
# ;
#
# ;
#
let mut linter = new;
linter.register?;
linter.register?;
for line in "unused-value = deny\nshadowing = allow".lines
assert_eq!;
let typo = linter.set_level;
assert!;
# Ok::
With the serde feature, Level deserializes from the same lowercase strings, so a BTreeMap<String, Level> reads straight out of a TOML or JSON configuration file.
Examples
Three runnable examples ship in examples/, built on a miniature arithmetic language (parser and four rules in examples/common):
- Quick start — parse an expression, lint it, and render every finding with source context, including a multi-label diagnostic with a note.
- Configure — layer rule defaults, a project configuration file, and
-D/-W/-Aflags; list the effective configuration; report a misspelled rule and an invalid level. - Parallel — lint 2,000 files across every available core with one shared
Linter, each worker reusing a findings buffer throughrun_into.
Performance
A run is one iterative depth-first walk no matter how many rules are registered: each node is visited once and handed to every enabled rule in turn. Rules at Allow are never called, and a linter with nothing enabled returns without touching the tree. Apart from the walk's own stacks and the findings it produces, a run allocates nothing, and run_into lets a caller reuse one findings buffer across a whole batch of files.
Measured with the benchmarks in benches/ (Linux/WSL2, x86_64, Rust stable, release profile):
| Benchmark | What it measures | Result |
|---|---|---|
run/walk_raw |
A bare ast_lang::walk that only counts nodes — the traversal floor. |
~1.8–1.9 ns/node |
run/noop_rule |
One enabled rule that returns immediately — the framework's own cost. | ~4.7 ns/node |
run/example_rules |
The four example rules on a 135k-node tree, building real findings. | ~1.5 ms (~11 ns/node) |
rules/noop_x |
1 → 4 → 16 enabled no-op rules over 17k nodes. | ~1.0–1.2 ns/node per extra rule |
run/all_allowed |
Every rule allowed, 135k-node tree. | ~1.3–1.4 ns total (walk skipped) |
Run them yourself:
Criterion writes per-benchmark reports to target/criterion/. Numbers vary by CPU; compare the trend across runs, not a single absolute.
Design notes
- One walk, every rule. Rules are not passes. The linter walks the tree once and calls each enabled rule at each node, so the cost of a lint run grows with tree size, not with tree size times rule count.
- Rules are stateless; position comes from the context.
checktakes&self. Everything a rule needs about where it is — parent, ancestors, depth — comes from theContext, maintained by the walk at no extra cost. That is what makes a configured linter reusable and shareable. Send + Syncby construction. TheRuletrait requiresSend + Syncandruntakes&self, so one linter lints many files in parallel from a shared reference.- Deterministic output. Findings come back in depth-first pre-order, and within a node in rule registration order. The same tree and configuration always produce the same list.
- Deep trees are safe. The walk is iterative, so a 200,000-deep tree lints without growing the call stack; a stale root handle produces no findings instead of a panic.
- No glue types. Nodes are
ast-langnodes and findings carrydiag-langdiagnostics. Both share onespan-lang, so a node'sSpanlabels a diagnostic with no conversion, and the types are re-exported so a single dependency is enough.
Testing
The suite runs on Windows, Linux (WSL2 Ubuntu), and macOS through the CI matrix, on stable and the 1.85 MSRV:
Property tests in tests/proptests.rs check the runner against an independent model over randomly shaped trees and random configurations: the findings are exactly the enabled rules' matches, in pre-order, with the configured severity and the true node depth. Every rust example in this README and in docs/API.md is compiled and run as a doctest, so the published examples cannot drift from the API.
Cross-platform support
- Linux (x86_64, aarch64)
- macOS (x86_64, Apple Silicon)
- Windows (x86_64)
The crate uses no operating-system facilities and no platform-specific code; behaviour is identical on every target.
Contributing
See dev/DIRECTIVES.md for engineering standards and the definition of done. Before a PR: cargo fmt --all, cargo clippy --all-targets --all-features -- -D warnings, and cargo test --all-features must be clean.