Expand description
§lint_lang
A lint framework: named, configurable rules that run over a syntax tree and report what they find as diagnostics.
A compiler’s checks fall into two groups. Some are hard errors the language defines — a type mismatch, an unresolved name. Others are judgements: code that is legal but almost certainly a mistake, needlessly complex, or against a project’s style. Those belong in a linter, where each check is a separate rule the user can turn up to an error, down to a warning, or off entirely. lint-lang is the machinery for that second group. It owns no rules and no grammar; a language supplies both, and lint-lang runs the rules, applies the user’s configuration, and collects the results.
§The model
- A
Ruleis one check. It has a stablename, adefault_level, and acheckthat inspects one node and reports problems. - A
Level—Allow,Warn, orDeny— is how strictly a rule is applied. - A
Linterholds the registered rules and their levels, and runs them all over a tree in a single walk. - A
Contextis what a rule sees while checking a node: the arena, the node’s ancestors and depth, and thereportcall. - A
Findingis one reported problem: aDiagnostictagged with the rule that produced it.
Trees are the ones ast_lang defines: nodes of any type implementing
Node, stored in an Arena and linked by Id handles. Findings are
diag_lang diagnostics, so they render with source context through the same
renderer as every other error the compiler produces.
§Example
A two-variant expression type and a rule that flags adding zero.
use lint_lang::{Arena, Context, Id, Label, Level, Linter, Node, Rule, Span};
enum Expr {
Int(i64, Span),
Add(Id<Expr>, Id<Expr>, Span),
}
impl Node for Expr {
fn span(&self) -> Span {
match self {
Expr::Int(_, s) | Expr::Add(_, _, s) => *s,
}
}
fn each_child(&self, f: &mut dyn FnMut(Id<Self>)) {
if let Expr::Add(a, b, _) = self {
f(*a);
f(*b);
}
}
fn map_children(&self, f: &mut dyn FnMut(Id<Self>) -> Id<Self>) -> Self {
match self {
Expr::Int(v, s) => Expr::Int(*v, *s),
Expr::Add(a, b, s) => Expr::Add(f(*a), f(*b), *s),
}
}
}
struct AddZero;
impl Rule<Expr> for AddZero {
fn name(&self) -> &'static str {
"add-zero"
}
fn check(&self, node: &Expr, cx: &mut Context<'_, Expr>) {
let Expr::Add(a, b, span) = node else { return };
let arena = cx.arena();
let is_zero = |id: &Id<Expr>| matches!(arena.get(*id), Some(Expr::Int(0, _)));
if is_zero(a) || is_zero(b) {
cx.report("adding zero has no effect", Label::new(*span, "this addition"));
}
}
}
// `x + 0`, with `x` = 9
let mut arena = Arena::new();
let x = arena.alloc(Expr::Int(9, Span::new(0, 1)));
let zero = arena.alloc(Expr::Int(0, Span::new(4, 5)));
let sum = arena.alloc(Expr::Add(x, zero, Span::new(0, 5)));
let mut linter = Linter::new();
linter.register(AddZero)?;
let findings = linter.run(&arena, sum);
assert_eq!(findings.len(), 1);
assert_eq!(findings[0].to_string(), "warning[add-zero]: adding zero has no effect");
// The user decides how seriously to take it.
linter.set_level("add-zero", Level::Deny)?;
assert!(linter.run(&arena, sum)[0].is_error());§Performance
A run is one iterative depth-first walk, whatever the number of rules: each
node is visited once and handed to every enabled rule in turn. Disabled rules
are never called, a linter with nothing enabled does not walk at all, and the
only allocations a run makes are the walk’s own stacks and the findings
themselves. Linter::run_into reuses a caller’s buffer across runs.
§Features
std(default) — the standard library. Without it the crate is#![no_std]and needs onlyalloc. Forwards toast-lang/stdanddiag-lang/std.serde—SerializeandDeserializeforLevel, as the lowercase strings"allow","warn", and"deny", so rule levels can be read straight from a configuration file.
§Stability
The public surface is frozen and stable as of 1.0.0: it follows Semantic
Versioning, with no breaking changes before 2.0. The full surface, the
behavioural guarantees, and the SemVer promise are catalogued in
docs/API.md.
Structs§
- Arena
- A typed arena that allocates values and hands back stable
Idhandles. - Context
- The view a
Rulegets of the node it is checking, and the channel it reports findings through. - Diagnostic
- One thing a compiler stage has to say about the source: a
Severity, a headline message, a primaryLabelpointing at the span it concerns, and optionally secondary labels for related locations and trailing note/help lines. - Finding
- A single problem reported by a rule during a lint run.
- Id
- A small, copyable, type-tagged handle to one value in an
Arena. - Label
- A
Spanplus the text that explains what is at that span. - Linter
- A configured set of lint rules, and the runner that applies them to a tree.
- Span
- A half-open byte range
start..endinto a single source.
Enums§
- Level
- The level a rule runs at: off, reported as a warning, or reported as an error.
- Lint
Error - An error raised while configuring a
Linteror parsing aLevel. - Severity
- The level a diagnostic reports at — how serious it is and how it is labelled.