cpp_code_analysis 0.3.0

The analysis layer of cpp_ls: the preprocessor, symbol scopes, type inference and the semantic checks.
Documentation
//! **Every diagnostic this analysis can produce, as one code** — and the severity it is shown with.
//!
//! The shape follows `emmylua_code_analysis`'s `check/diagnostic_code.rs`: an enum whose variant names are the
//! codes in kebab case, one `///` line per variant saying what it means, and the answers (`all`, `name`,
//! `severity`) derived from the enum itself rather than from a table beside it.
//!
//! # Why the name is *derived* and not written twice
//!
//! ```text
//!   the module        param_type_check.rs        the check's own file, snake case
//!   the variant       DiagnosticCode::ParamTypeCheck
//!   the code          "param-type-check"         what a client shows and a config file names
//! ```
//!
//! Three spellings of one rule, and [`DiagnosticCode::name`] is the only place the third is written. A check that
//! reported a code it did not mean cannot be written — it reports a **variant**, not a string — and a new variant
//! without a name or a severity is a compile error rather than a rule that publishes an empty string.
//!
//! # Severity is a property of the rule
//!
//! Not of the finding: "this name is not used" and "this file does not parse" are different kinds of claim and the
//! difference belongs to the rule, stated once. [`DiagnosticCode::severity`] is what the LSP layer puts in
//! `Diagnostic::severity`, and it is the same answer for every finding of that rule.
//!
//! # Suppressing a rule, when it comes
//!
//! Two forms, and both are already shaped by this enum:
//!
//! ```text
//!   by name    a config lists codes; `from_name` turns each into a variant, and an unknown one is *reported*
//!              to the user rather than silently ignored
//!   by line    a comment on a line names a code — that belongs in `CheckContext::add_diagnostic`, which is the
//!              one place a finding becomes a diagnostic, so that a check never has to know it was suppressed
//! ```
//!
//! Nothing suppresses anything yet. [`CheckConfig`](super::config::CheckConfig) is where the first form will live.

/// **One rule this analysis has.**
///
/// See the module documentation for the three spellings of a rule and for why the code is derived.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub enum DiagnosticCode {
    /// The file does not parse — see [`super::syntax_error`].
    SyntaxError,
    /// An argument's type does not convert to the parameter it is passed for — see [`super::param_type_check`].
    ParamTypeCheck,
    /// A value does not convert to the type it is assigned to or initialised as — see [`super::assign_type_check`].
    AssignTypeCheck,
    /// A member access on a type that does not declare that member — see [`super::undefined_field`].
    UndefinedField,
    /// A name nothing declares is read at this position — see [`super::undefined_name`].
    UndefinedName,
    /// A name declared twice in one scope, where the language has no reading for it — see
    /// [`super::redefinition`].
    Redefinition,
    /// A declaration nothing uses — see [`super::unused`].
    Unused,
    /// A branch the program cannot take, or a condition that is already decided — see
    /// [`super::unnecessary_branch`].
    UnnecessaryBranch,
    /// More arguments than the callee takes, or fewer than it needs — see [`super::argument_count`].
    ArgumentCount,
    /// A `return` whose expression does not convert to the function's return type — see
    /// [`super::return_type_mismatch`].
    ReturnTypeMismatch,
    /// A macro defined twice with different replacement lists — see [`super::macro_redefined`].
    MacroRedefined,
    /// An argument whose type does not satisfy the concept constraining its parameter — see
    /// [`super::concept_not_satisfied`].
    ConceptNotSatisfied,
    /// A `#include` that names a file nobody can find — see [`super::include_not_found`].
    ///
    /// Separate from [`DiagnosticCode::SyntaxError`] for the reason a reader needs it separate: the file parses
    /// perfectly, and what is missing is a file it named.
    IncludeNotFound,
    /// **A type this file uses but does not include or import** — see [`super::missing_include`].
    ///
    /// The finding a reader turns into a fix: `Widget w;` compiles only because something upstream happened to include
    /// `widget.h`, and the file should say so itself. The rule never names the standard library — see the module.
    MissingInclude,
    /// A member reached from somewhere that may not reach it - see [`super::access_invisible`].
    AccessInvisible,
    /// A function declared to return something whose body never returns - see [`super::missing_return`].
    MissingReturn,
    /// `=` where the reader almost certainly meant `==` - see [`super::assignment_in_condition`].
    AssignmentInCondition,
    /// **A note about a module import**, which the analysis knows rather than complains about — see
    /// [`Session::notes_about_the_modules`](crate::Session::notes_about_the_modules).
    ///
    /// Not a check: nothing is wrong with the file, and the reader is told where a file they named is. It is a code
    /// because it is a diagnostic a client shows, and the point of the enum is that **everything shown has one**.
    ModuleNote,
    /// `if (x)` / `for (…)` / `while (…)` whose body is a single statement — see [`super::braces_around_statements`].
    BracesAroundStatements,
    /// `NULL` where `nullptr` is meant — see [`super::use_nullptr`].
    UseNullptr,
    /// A `virtual` member function that overrides without saying `override` — see [`super::use_override`].
    UseOverride,
    /// `if (x == true)` and its siblings — see [`super::simplify_boolean_expr`].
    SimplifyBooleanExpr,
    /// An `else` after a branch that returns — see [`super::else_after_return`].
    ElseAfterReturn,
    /// A C-style cast — see [`super::cstyle_cast`].
    CStyleCast,
    /// An iterator declared by its full spelling — see [`super::use_auto`].
    UseAuto,
    /// A macro body that needs its own parentheses — see [`super::macro_parentheses`].
    MacroParentheses,
    /// A non-boolean value used as a condition — see [`super::implicit_bool_conversion`].
    ImplicitBoolConversion,
    /// A reference, pointer or view of something that dies when the function returns — see
    /// [`super::dangling_return`].
    DanglingReturn,
    /// A view, reference or pointer member that borrows something which does not outlive the object — see
    /// [`super::dangling_field`].
    DanglingField,
    /// A pointer read after the memory it refers to was freed — see [`super::use_after_free`].
    UseAfterFree,
    /// A type declared with Unreal Engine's `UCLASS`/`USTRUCT`/`UENUM` and a name missing the prefix the engine
    /// requires — see [`super::ue_naming`].
    UeNaming,
    /// A `UCLASS`/`USTRUCT` whose body writes no `GENERATED_BODY()` — see [`super::ue_generate_body`].
    UeGenerateBody,
    /// A file with reflection annotations and no `*.generated.h` include, or one that is not the last include — see
    /// [`super::ue_generated_header`].
    UeGeneratedHeader,
    /// A `UPROPERTY`/`UFUNCTION` on something the build tool does not reflect — see [`super::ue_macro_scope`].
    UeMacroScope,
    /// A reflection specifier the engine does not know, which the build tool silently ignores — see
    /// [`super::ue_specifier`].
    UeSpecifier,
}

impl DiagnosticCode {
    /// **Every code, in the order a list reads in.**
    ///
    /// The order is the one the module documentation of [`super`] describes: what the text *is* (the parse), then
    /// what it says about types, then what it says about a whole body, then the two that are about the reading
    /// rather than the program. A consumer that shows a settings screen, or a test that asserts every rule has a
    /// name and a module, iterates this.
    pub const ALL: [DiagnosticCode; 35] = [
        DiagnosticCode::SyntaxError,
        DiagnosticCode::ParamTypeCheck,
        DiagnosticCode::AssignTypeCheck,
        DiagnosticCode::UndefinedField,
        DiagnosticCode::UndefinedName,
        DiagnosticCode::Redefinition,
        DiagnosticCode::Unused,
        DiagnosticCode::UnnecessaryBranch,
        DiagnosticCode::ArgumentCount,
        DiagnosticCode::ReturnTypeMismatch,
        DiagnosticCode::MacroRedefined,
        DiagnosticCode::IncludeNotFound,
        DiagnosticCode::MissingInclude,
        DiagnosticCode::AccessInvisible,
        DiagnosticCode::MissingReturn,
        DiagnosticCode::AssignmentInCondition,
        DiagnosticCode::ModuleNote,
        DiagnosticCode::BracesAroundStatements,
        DiagnosticCode::UseNullptr,
        DiagnosticCode::UseOverride,
        DiagnosticCode::SimplifyBooleanExpr,
        DiagnosticCode::ElseAfterReturn,
        DiagnosticCode::CStyleCast,
        DiagnosticCode::UseAuto,
        DiagnosticCode::MacroParentheses,
        DiagnosticCode::ImplicitBoolConversion,
        DiagnosticCode::ConceptNotSatisfied,
        DiagnosticCode::DanglingReturn,
        DiagnosticCode::DanglingField,
        DiagnosticCode::UseAfterFree,
        DiagnosticCode::UeNaming,
        DiagnosticCode::UeGenerateBody,
        DiagnosticCode::UeGeneratedHeader,
        DiagnosticCode::UeMacroScope,
        DiagnosticCode::UeSpecifier,
    ];

    /// **The code a client is shown**, and the spelling a config file uses: kebab case, and the module's file name
    /// is the snake-case form of it (`param-type-check` ↔ `param_type_check.rs`).
    ///
    /// The `match` has no `_` arm on purpose. A new variant without a name is a compile error, which is the only
    /// way to be sure that no rule ever reaches a client unnamed.
    pub fn name(self) -> &'static str {
        match self {
            DiagnosticCode::SyntaxError => "syntax-error",
            DiagnosticCode::ParamTypeCheck => "param-type-check",
            DiagnosticCode::AssignTypeCheck => "assign-type-check",
            DiagnosticCode::UndefinedField => "undefined-field",
            DiagnosticCode::UndefinedName => "undefined-name",
            DiagnosticCode::Redefinition => "redefinition",
            DiagnosticCode::Unused => "unused",
            DiagnosticCode::UnnecessaryBranch => "unnecessary-branch",
            DiagnosticCode::ArgumentCount => "argument-count",
            DiagnosticCode::ReturnTypeMismatch => "return-type-mismatch",
            DiagnosticCode::MacroRedefined => "macro-redefined",
            DiagnosticCode::IncludeNotFound => "include-not-found",
            DiagnosticCode::MissingInclude => "missing-include",
            DiagnosticCode::AccessInvisible => "access-invisible",
            DiagnosticCode::MissingReturn => "missing-return",
            DiagnosticCode::AssignmentInCondition => "assignment-in-condition",
            DiagnosticCode::ModuleNote => "module-note",
            DiagnosticCode::BracesAroundStatements => "braces-around-statements",
            DiagnosticCode::UseNullptr => "use-nullptr",
            DiagnosticCode::UseOverride => "use-override",
            DiagnosticCode::SimplifyBooleanExpr => "simplify-boolean-expr",
            DiagnosticCode::ElseAfterReturn => "else-after-return",
            DiagnosticCode::CStyleCast => "cstyle-cast",
            DiagnosticCode::UseAuto => "use-auto",
            DiagnosticCode::MacroParentheses => "macro-parentheses",
            DiagnosticCode::ImplicitBoolConversion => "implicit-bool-conversion",
            DiagnosticCode::DanglingReturn => "dangling-return",
            DiagnosticCode::DanglingField => "dangling-field",
            DiagnosticCode::UseAfterFree => "use-after-free",
            DiagnosticCode::UeNaming => "ue-naming",
            DiagnosticCode::UeGenerateBody => "ue-generate-body",
            DiagnosticCode::UeGeneratedHeader => "ue-generated-header",
            DiagnosticCode::UeMacroScope => "ue-macro-scope",
            DiagnosticCode::UeSpecifier => "ue-specifier",
            DiagnosticCode::ConceptNotSatisfied => "concept-not-satisfied",
        }
    }

    /// **The code as a rule**, or `None` for a code this build does not have.
    ///
    /// The inverse of [`DiagnosticCode::name`], and the round trip is asserted for every variant. A config reader
    /// uses this so that a misspelled rule is *reported* — treating an unknown name as "no rules" turns a typo into
    /// a silently disabled analysis, which is the failure mode this layer's contract is written against.
    pub fn from_name(name: &str) -> Option<DiagnosticCode> {
        DiagnosticCode::ALL
            .into_iter()
            .find(|code| code.name() == name)
    }

    /// **How a client should draw it.**
    ///
    /// This crate does not speak LSP — the severities are its own, and the server maps them — for the reason it
    /// does not speak LSP anywhere else: the analysis is usable by a batch tool that has no protocol at all.
    pub fn severity(self) -> RuleSeverity {
        match self {
            // **A parse error stops everything.** The file does not mean anything until it is fixed, and no other
            // rule's finding can be trusted while the text does not parse.
            DiagnosticCode::SyntaxError => RuleSeverity::Error,
            // **A name that is not there, a call that cannot be made, a type that does not fit.** These are the
            // language's own complaints: the program will not build.
            DiagnosticCode::IncludeNotFound => RuleSeverity::Error,
            // A judgement rather than a law: the file compiles while something upstream includes the header, and the
            // finding says the file should say so itself. The standard library is never named — see the module.
            DiagnosticCode::MissingInclude => RuleSeverity::Warning,
            DiagnosticCode::ParamTypeCheck => RuleSeverity::Error,
            DiagnosticCode::AssignTypeCheck => RuleSeverity::Error,
            DiagnosticCode::UndefinedField => RuleSeverity::Error,
            DiagnosticCode::UndefinedName => RuleSeverity::Error,
            DiagnosticCode::Redefinition => RuleSeverity::Error,
            DiagnosticCode::ArgumentCount => RuleSeverity::Error,
            DiagnosticCode::ReturnTypeMismatch => RuleSeverity::Error,
            DiagnosticCode::ConceptNotSatisfied => RuleSeverity::Error,
            // **A judgement rather than a law.** A macro redefined with a different body is legal in some
            // translation units and a bug in most; a branch that cannot run is dead code rather than a mistake.
            // Both draw attention without claiming the program is broken.
            DiagnosticCode::MacroRedefined => RuleSeverity::Warning,
            DiagnosticCode::UnnecessaryBranch => RuleSeverity::Warning,
            // **A hint, which is the quietest thing a client can draw** — a dotted underline in VS Code, nothing at
            // all in several others. "Nothing reads this name" is the least urgent claim this analysis makes: the
            // program builds, runs, and may be exactly what the author meant while they were writing it.
            DiagnosticCode::Unused => RuleSeverity::Hint,
            // **A member another class may not reach, and a body that never returns what it promises**: both are
            // complaints about a program that will not build.
            DiagnosticCode::AccessInvisible => RuleSeverity::Error,
            DiagnosticCode::MissingReturn => RuleSeverity::Error,
            // A judgement rather than a law: an assignment in a condition is deliberate in a great deal of code.
            DiagnosticCode::AssignmentInCondition => RuleSeverity::Warning,
            DiagnosticCode::ModuleNote => RuleSeverity::Information,
            // **The style checks are hints**: none of them is a program that will not build, and the quietest rendering
            // is the one that lets a reader keep them off without losing an error's squiggle.
            DiagnosticCode::BracesAroundStatements => RuleSeverity::Hint,
            DiagnosticCode::UseNullptr => RuleSeverity::Hint,
            DiagnosticCode::UseOverride => RuleSeverity::Hint,
            DiagnosticCode::SimplifyBooleanExpr => RuleSeverity::Hint,
            DiagnosticCode::ElseAfterReturn => RuleSeverity::Hint,
            // A C-style cast is the one of these that a project's guidelines usually forbid rather than merely prefer.
            DiagnosticCode::CStyleCast => RuleSeverity::Warning,
            DiagnosticCode::UseAuto => RuleSeverity::Hint,
            // A macro body without its own parentheses is a bug in the *caller's* expression order, not a style question.
            DiagnosticCode::MacroParentheses => RuleSeverity::Warning,
            DiagnosticCode::ImplicitBoolConversion => RuleSeverity::Hint,
            // A dangling reference is undefined behaviour rather than a style question: the program reads an object
            // whose lifetime ended, which is the one class of defect a compiler must not be quiet about.
            DiagnosticCode::DanglingReturn => RuleSeverity::Error,
            DiagnosticCode::DanglingField => RuleSeverity::Error,
            DiagnosticCode::UseAfterFree => RuleSeverity::Error,
            // A name is a convention rather than a broken program.
            DiagnosticCode::UeNaming => RuleSeverity::Hint,
            // **A `UCLASS` without `GENERATED_BODY()` does not compile in Unreal** — the macro declares the reflection
            // data and the generated constructor the engine links against.
            DiagnosticCode::UeGenerateBody => RuleSeverity::Error,
            // **The build fails without the generated header**, the same shape as the missing body macro: the
            // declaration is fine, and the engine build tool is what rejects it.
            DiagnosticCode::UeGeneratedHeader => RuleSeverity::Error,
            // **The program compiles**; what is wrong is the expectation the annotation sets, which is a warning.
            DiagnosticCode::UeMacroScope => RuleSeverity::Warning,
            // **The program builds and the specifier is ignored**, which reads exactly like success: a warning.
            DiagnosticCode::UeSpecifier => RuleSeverity::Warning,
        }
    }

    /// **What a client may grey out** — the protocol's `DiagnosticTag`, as this crate's own vocabulary.
    ///
    /// A tag is not a severity: a warning can be tagged `Unnecessary` and so can a hint. It says *why* the reader
    /// is being told, which is what a client needs to render the code as struck through rather than merely
    /// underlined — the difference between "look at this" and "this does nothing".
    ///
    /// Per **code** rather than per finding, for the same reason severity is: "nothing uses this name" is what the
    /// rule says, and it says it about every finding it produces.
    pub fn tags(self) -> &'static [RuleTag] {
        match self {
            DiagnosticCode::Unused => &[RuleTag::Unnecessary],
            DiagnosticCode::UnnecessaryBranch => &[RuleTag::Unnecessary],
            _ => &[],
        }
    }

    /// Is this code a **claim that something is wrong**, as opposed to something the reader is told?
    ///
    /// [`DiagnosticCode::ModuleNote`] is the only one that is not, and the distinction is the one the diagnostics
    /// channel already makes: a note draws no squiggle and does not count towards "this file has problems".
    pub fn is_a_complaint(self) -> bool {
        !matches!(self, DiagnosticCode::ModuleNote)
    }

    /// **Is this rule about C++ only?** — the question a C project's diagnostics turn on.
    ///
    /// Two kinds of code answer yes, and they are one answer for the same reason: a rule that names C++ grammar cannot
    /// fire in a C file, and a rule that names C++ *style* must not. `cstyle-cast` is the second kind — in C, a C-style
    /// cast is the only cast there is, so telling a C program to write `static_cast` is telling it to write C++.
    /// `use-nullptr` is the same: `NULL` is what C has, and C23's `nullptr` is a different question from the modernise
    /// one. `implicit-bool-conversion` belongs here too, because an `int` in a condition is the language's own idiom in
    /// C, and a reader who turns this server on for a C project asked for C to be read rather than rewritten.
    ///
    /// Measured before this existed: a C corpus configured with `-std=c17` answered **14 `cstyle-cast` findings**
    /// telling the program to write `static_cast`, and the same shape of noise was available to every rule below.
    ///
    /// A project that states no language gets **all** of them: "not told" is not "C", and a feature disappearing
    /// without a word is worse than a finding a project can switch off.
    pub fn is_cpp_only(self) -> bool {
        matches!(
            self,
            DiagnosticCode::UseNullptr
                | DiagnosticCode::UseAuto
                | DiagnosticCode::UseOverride
                | DiagnosticCode::CStyleCast
                | DiagnosticCode::AccessInvisible
                | DiagnosticCode::ConceptNotSatisfied
                | DiagnosticCode::DanglingField
                | DiagnosticCode::ModuleNote
                | DiagnosticCode::ImplicitBoolConversion
                | DiagnosticCode::UeNaming
                | DiagnosticCode::UeGenerateBody
                | DiagnosticCode::UeGeneratedHeader
                | DiagnosticCode::UeMacroScope
                | DiagnosticCode::UeSpecifier
        )
    }

    /// **Does this rule only make sense in Unreal Engine code?** — the switch `[unreal] enable` turns.
    ///
    /// The two answers are one kind: `ue-naming` and `ue-generate-body` name conventions and macros of that engine, and
    /// a project that never writes `UCLASS()` has nothing for them to say. Like [`DiagnosticCode::is_cpp_only`], "not
    /// told" is not the answer either way — a project that does not say it is Unreal is not treated as one.
    pub fn is_unreal_only(self) -> bool {
        matches!(
            self,
            DiagnosticCode::UeNaming
                | DiagnosticCode::UeGenerateBody
                | DiagnosticCode::UeGeneratedHeader
                | DiagnosticCode::UeMacroScope
                | DiagnosticCode::UeSpecifier
        )
    }
}

/// **What a client may grey out** — the protocol calls these tags, and this is the crate's own vocabulary for them.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub enum RuleTag {
    /// The code does nothing: an unused name, a branch that cannot run.
    Unnecessary,
}

/// **How a diagnostic is drawn**, in this crate's own vocabulary — see [`DiagnosticCode::severity`].
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub enum RuleSeverity {
    /// The program will not build, or the text does not parse.
    Error,
    /// Something is wrong in a way the language permits — dead code, a redefinition.
    Warning,
    /// The quietest level: a suggestion a client may draw as a dotted underline.
    Hint,
    /// Not a complaint at all — a fact about where a file is.
    Information,
}