Skip to main content

Module check

Module check 

Source
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 wrote

A 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 NOTHING

The 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-function and contract-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-derived and override-of-final — the two ways final refuses a hierarchy.
final_misplaced
final-misplaced — final on a function that is neither virtual nor overriding.
include_not_found
include-not-found: an #include whose file is not there.
macro_redefined
macro-redefined: a #define that 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 — override written 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: a return whose 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§

CheckContext
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.
FunctionHead
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 — f for f(x), push_back for v.push_back(x), free for ns::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, struct or union.
is_a_function_definition
Is this node a function definition? See function_definitions for 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_back in v.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_head reads 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.