Expand description
Semantic checks: what the analysis can say about a file that is wrong, as opposed to what it read.
crate::FileDiagnostics::errors is the parser’s answer — the text does not parse — and
crate::FileDiagnostics::notes is what the analysis knows but is not a complaint. This is the third thing a
diagnostics channel needs: a construct the grammar accepts and the language does not.
§The shape of a check
One rule, one file, and one impl:
pub struct Unused;
impl Check for Unused {
const CODES: &'static [DiagnosticCode] = &[DiagnosticCode::Unused];
fn check(context: &mut CheckContext<'_>) {
// … and `context.add(code, range, name, message)` is how a finding is reported
}
}The file’s name is the snake-case spelling of the code it reports — unused.rs reports unused,
param_type_check.rs reports param-type-check — so grep unused finds the rule, its tests and its
documentation in one pass. DiagnosticCode is the enum those codes come from, and its name is the only
place the kebab spelling is written.
The shape follows emmylua_code_analysis’s check/checker: a Check trait carrying the codes it may report,
a CheckContext that collects findings and filters them through a CheckConfig, and a run that is a flat
list of typed calls.
§A decision comes from the tree; text is for messages
The crate has a lossless tree and a lexer, and every question a check asks has a node or a token for its
answer: an access label is a PublicAccess node beside a ClassBody, a class is a ClassKeyword token on a
ClassDef, a declarator is a Declarator node, a condition is a ParenExpr node. Reaching past those for the
text is how this layer produced its first user-visible false positive: assignment_in_condition looked for the
first ( and its match in the text of an if, counted a < in i + 1 < argc as an opening bracket, ran on
into the body, found an = in the first statement there, and reported = in a condition is almost always a
== on a line whose condition is two comparisons.
So:
to decide walk nodes (`children`, `descendants`) and tokens (`descendants_with_tokens`)
to say text: the message, and `source[range]` to quote what the reader wroteA text comparison is allowed where the token is the answer - a keyword token compared against "class" has
the lexer’s boundary around it, which is the whole difference from a substring search. Where a check still reads
text, the reason belongs in a comment beside it, and the honest reasons are narrow: a question about layout
(a directive’s own line), or a conservative approximation of a control-flow question that a tree walk over one
file cannot answer.
§Why run is a list of run_check::<T> and not a list of closures
It was the other shape — timed(0, &|| …), timed(1, &|| …) — and the index was the defect: a check’s name
lived in a second table (crate::stages), keyed by the same numbers, so adding a rule meant editing two lists
and keeping them in step by hand, with nothing checking that they were. The type carries the name now, the
table is gone, and a check that is not in run does not exist rather than silently never running.
§No timer
The checks are not timed. They were — a guard per check, with a stage name — and the instrumentation was
removed because it does not fit what it measures: diagnostics run on every keystroke, so a timer here is a
lock, an allocation and a line of output per check per keystroke, paid by every user to answer a question one
developer asks once. When the cost of this layer needs measuring, the measurement is a probe
(examples/checks_timing.rs), which can afford to be intrusive because it runs when somebody asks it to.
§The contract: Known::Yes or Known::No, and nothing else
A check reports only what it knows. Known has three values and this layer has two:
Known::Yes(_) the question was answered, and the answer is a problem -> report
Known::No the question was asked and the answer is a definite no -> report, for a "not found"
Known::Unknown the question was not answered, for a stated reason -> report NOTHINGThe third is not a gap in this layer, it is the design of the layer underneath it.
sema::resolve keeps the two “no“s apart on purpose: Known::No means a name is
nowhere, and UnknownReason::NotDeclaredHere means it is
somewhere else — usually a header the analysis has not read. The first is a fact about the file; the second
is a fact about us.
§Why a check that reports nothing is the ordinary case, and why that is the point
The failure mode this layer has to avoid is not missing a problem, it is inventing one, because an editor that underlines correct code is one the user turns off — and then it reports nothing at all, forever. The measurement that keeps it honest is a corpus that is known good: the standard library. A check that reports anything at all on a header it read correctly is wrong, and that is a test that can fail.
Re-exports§
pub use config::CheckConfig;pub use diagnostic_code::DiagnosticCode;pub use diagnostic_code::RuleSeverity;pub use diagnostic_code::RuleTag;
Modules§
- abstract_
class_ instantiated abstract-class-instantiated— a by-value variable whose class type is abstract.- access_
invisible access-invisible: a member reached from somewhere that may not reach it.- argument_
count argument-count: a call that passes more arguments than the callee takes, or fewer than it needs.- assign_
type_ check assign-type-check: a value that does not convert to the type it is assigned to.- assignment_
in_ condition assignment-in-condition:=where the reader almost certainly meant==.- concept_
not_ satisfied concept-not-satisfied— an argument whose type does not satisfy the concept its parameter is constrained by.- config
- Which rules are on — the config a check run is filtered through.
- contract_
placement contract-on-virtual-functionandcontract-on-defaulted-function— the two contract placements C++26 refuses.- diagnostic_
code - Every diagnostic this analysis can produce, as one code — and the severity it is shown with.
- final_
hierarchy final-class-derivedandoverride-of-final— the two waysfinalrefuses a hierarchy.- final_
misplaced final-misplaced—finalon a function that is neither virtual nor overriding.- include_
not_ found include-not-found: an#includewhose file is not there.- macro_
redefined macro-redefined: a#definethat changes a name whose definition is already in force.- missing_
return missing-return: a function declared to return something, whose body never returns.- override_
nonexistent override-nonexistent—overridewritten on a function that no base class declares.- param_
type_ check param-type-check: an argument whose type does not convert to the parameter it is passed for.- pure_
virtual_ not_ overridden pure-virtual-not-overridden— a class that implements some of its base’s pure virtuals but not all.- redefinition
redefinition: a name declared twice in one scope.- return_
type_ mismatch return-type-mismatch: areturnwhose expression does not convert to the function’s return type.- syntax_
error syntax-error: the file does not parse, and the parser said where.- undefined_
field undefined-field: a member access on a type that does not declare that member.- undefined_
name undefined-name: a name read where nothing declares it.- unnecessary_
branch unnecessary-branch: a branch the program cannot take, or a condition that is already decided.- unused
unused: a local declaration nothing reads.
Structs§
- Check
Context - Everything a check is given, and where it puts what it found.
- Finding
- What a check found, in the form a diagnostics channel shows it.
- Function
Head - The three parts of a function’s head, read once: what it returns, what it is called, and where that name is.
Traits§
- Check
- A check: one rule, and the codes it may report.
Functions§
- a_
class_ can_ be_ built_ from - Can a value of this type build an object of that class? — asked of the index, never of a tree.
- a_
literal_ zero - Is this expression the literal
0— the null pointer constant, which converts to every pointer type? - body_of
- The body of a function definition, when it has one.
- callee_
name_ of - The name a call is to —
fforf(x),push_backforv.push_back(x),freeforns::free(p). - condition_
of - The condition of an
if/while/switch, taken from the node and never from its text. - function_
definitions - Every function definition in this file’s own text.
- function_
head - Read a function’s head — see
FunctionHead. - is_
a_ class_ definition - Is this node a class-like definition? —
class,structorunion. - is_
a_ function_ definition - Is this node a function definition? See
function_definitionsfor why the question is about shape. - literal_
condition_ of - The one word a condition is, when it is a bare literal —
true,false. - member_
access_ above - The member access a callee is the name of —
push_backinv.push_back(…). - name_
declared_ by - The name a function declares — see
function_head, which reads it together with the return type and therefore cannot disagree with it about which name it found. - name_
token_ of - The name token a declaration or definition writes — the last non-trivia token before its parameter list.
- parameter_
spellings_ of - A function’s parameters as the declaration spells them —
int count,const Widget& w,.... - return_
type_ written_ by - The return type a function definition writes, as
function_headreads it. - run
- Run every check, in the order a consumer should show them, and answer what they found.
- run_
check - Run one check, unless every code it reports is turned off.
- spelling_
of - The last identifier written inside a node — the name a call would spell, the name a declaration declares.
- the_
returns_ in - The
returns a function’s body holds, without the ones a nested lambda owns.