cpp_code_analysis 0.1.3

The analysis layer of cpp_ls: the preprocessor, symbol scopes, type inference and the semantic checks.
Documentation
//! **Every diagnostic probe in this crate, and the one place each is read from the environment.**
//!
//! # Why this module exists
//!
//! These are debugging switches: `CPPLS_TRACE_MEMBERS=1` prints why a member query answered what it
//! answered, `CPPLS_TRACE_DIAGNOSTICS=1` prints the stage table.
//!
//! ```text
//! if std::env::var_os("CPPLS_TRACE_COOKING").is_some() { … }
//! ```
//!
//! at the point of use, and that has two costs, both measured on an index of `EmmyLuaCodeStyle`:
//!
//! * **The read is not free.** `std::env::var_os` takes a lock of the process environment on Windows. On a path
//!   taken nine million times, hoisting one of these reads behind a `LazyLock` took a single function from
//!   **271 s to 192 s**, and removing the `to_string_lossy` beside it took it to **165 s**. The same shape in
//!   `Condition::holds` was another **40 s**.
//! * **It cannot be found.** The gates were in eight files and no listing showed them together, so the same mistake
//!   was made in four places before anyone grepped for it.
//!
//! So every probe is a `fn() -> bool` over a `OnceLock`, and the answer is an atomic load. `on` is not a
//! pessimisation of `on`: a variable cannot appear in the middle of a run, and every caller read it to decide the
//! same thing for the whole process anyway.
//!
//! # Which of these are hot
//!
//! `cooking`, `macro`, `guard`, `lookup`, `coordinates` and `members` are consulted per macro, per condition, or per
//! symbol — millions of times per index. The rest are per file or per stage. **Do not add a probe whose gate is not
//! one of these functions**, which is the whole point of the module: the read happens here, once, or not at all.
//!
//! # Turning them on
//!
//! Each is its own variable, and an unset or empty one means off. They print to the process's own diagnostics — most
//! use `eprintln!`, and `diagnostics` is read by `crate::stages` to print the stage table at the end of a run.

/// Read one switch, once, for the life of the process.
///
/// `On`/`Off` rather than a `bool` cache so that a caller can hold the answer: `probes::ON.are_we()`. The `OnceLock`
/// is what makes the second and later calls an atomic load rather than a lock of the environment.
/// **The rule every switch applies: unset or empty means off, anything else means on.** One function rather than an
/// `is_some_and` written into the macro, so the rule has a test — the six hot callers all depend on it, and a
/// variable set to nothing being read as "on" would print a trace nobody asked for, millions of times.
fn is_on(value: Option<std::ffi::OsString>) -> bool {
    value.is_some_and(|value| !value.is_empty())
}

macro_rules! switch {
    ($($name:ident => $variable:literal, $documentation:literal;)*) => {
        $(
            #[doc = $documentation]
            pub fn $name() -> bool {
                static HELD: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
                *HELD.get_or_init(|| is_on(std::env::var_os($variable)))
            }
        )*
    };
}

switch! {
    cooking => "CPPLS_TRACE_COOKING", "What the cooker did to one unit: the directives it read and the facts it made.";
    macro_ => "CPPLS_TRACE_MACRO", "One macro name, at every lookup, with everything the expander will see.";
    guard => "CPPLS_TRACE_GUARD", "One condition, at every evaluation, on the walk's own path.";
    lookup => "CPPLS_TRACE_LOOKUP", "One name, at every lookup, on the walk's environment.";
    coordinates => "CPPLS_TRACE_COORDINATES", "Why a position resolved to the node it did.";
    members => "CPPLS_TRACE_MEMBERS", "Why a member query answered what it answered.";
    completion => "CPPLS_TRACE_COMPLETION", "What one completion request considered, region by region.";
    attributes => "CPPLS_TRACE_ATTR", "Attribute questions, as the walk asks them.";
    units => "CPPLS_TRACE_UNITS", "Which units the session walked, and how often each root.";
    diagnostics => "CPPLS_TRACE_DIAGNOSTICS", "The stage table, printed when a run ends.";
    timing => "CPPLS_TRACE_TIME", "Every type inference, and every file a question had to read to answer one.";
    no_inference => "CPPLS_NO_INFERENCE", "Answer every type question `Unknown`, so that a rule's own walk can be measured apart from the inference.";
    no_index_lookup => "CPPLS_NO_INDEX_LOOKUP", "Answer every declaration query `NotDeclaredHere`, so that a pull's cost can be split into the engine and the index — the sibling of `CPPLS_NO_INFERENCE`.";

    inference => "CPPLS_TRACE_INFERENCE", "What a member answer was substituted with, and the type it became — the switch two editor reports needed.";
    answers => "CPPLS_TRACE_ANSWERS", "What one name query found: how many declarations, of which kinds, in which files — the question a hover on a template parameter turned on (2288 `_Tp` answers, none of them a class).";

    view => "CPPLS_TRACE_VIEW", "Which rendering a query was answered from, and whether the cache had one: the question that separated `not cooked` from `cooked and dropped`.";
    types => "CPPLS_TRACE_TYPES", "One line per type question, at its depth — the only instrument that showed a recursion no depth limit bounded.";
    visibility => "CPPLS_TRACE_VISIBILITY", "How many files a visibility question kept, after the ordering step.";
    splice => "CPPLS_SPLICE_TRACE", "Every file the session entered and spliced, with what it contributed — the trace a missing standard-library fact needed.";
    inlay => "CPPLS_TRACE_INLAY", "Where an inlay-hint request's milliseconds went, one line per call.";
    time_checks => "CPPLS_TIME_CHECKS", "One line per rule per file — names the check that takes the forty-five seconds.";
    walk_census => "CPPLS_WALK_CENSUS", "Every file the walk entered, spliced or fresh, and the conditions it mentions.";
    code_action => "CPPLS_TRACE_CODE_ACTION", "Where a code-action request's milliseconds went.";
    no_share => "CPPLS_NO_SHARE", "Turn summary sharing off, so one machine can be measured with and without it — an A/B switch, not a setting.";
}

/// **Do not filter a candidate whose declaration is written in a `#if` region.**
///
/// The measurement behind deleting the lookup-time guard patch: with ⑱ (a file with a rendering is
/// read through it) the filter has almost nothing left to remove, and "almost nothing" is a number
/// this crate asks for rather than a claim.
pub fn no_guard_filter() -> bool {
    static SEEDED: std::sync::OnceLock<()> = std::sync::OnceLock::new();
    SEEDED.get_or_init(|| {
        NO_GUARD_FILTER.store(
            is_on(std::env::var_os("CPPLS_NO_GUARD_FILTER")),
            std::sync::atomic::Ordering::Relaxed,
        );
    });
    NO_GUARD_FILTER.load(std::sync::atomic::Ordering::Relaxed)
}

/// Turn [`no_guard_filter`] on or off at run time — for a probe comparing the two answers, and for a test.
pub fn set_no_guard_filter(on: bool) {
    // Read once first, so the environment's value cannot land *after* this call and overwrite it.
    let _ = no_guard_filter();
    NO_GUARD_FILTER.store(on, std::sync::atomic::Ordering::Relaxed);
}

static NO_GUARD_FILTER: std::sync::atomic::AtomicBool = std::sync::atomic::AtomicBool::new(false);
///
/// The question the plan turns on is not "how many files are indexed" but "how many of them a session actually reads
/// summary by summary". A window over the redb rows is only worth its cost if that number is small compared with the
/// index; this counter is what answers it, at the one place every reader goes through
/// (`ProjectIndex::summary`).
pub fn summaries() -> bool {
    static HELD: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
    *HELD.get_or_init(|| is_on(std::env::var_os("CPPLS_TRACE_SUMMARIES")))
}

fn summary_reads() -> &'static std::sync::Mutex<SummaryReads> {
    static HELD: std::sync::OnceLock<std::sync::Mutex<SummaryReads>> = std::sync::OnceLock::new();
    HELD.get_or_init(|| std::sync::Mutex::new(SummaryReads::default()))
}

#[derive(Default)]
struct SummaryReads {
    calls: usize,
    distinct: std::collections::HashSet<String>,
}

/// One call, and the file it was about.
pub fn a_summary_was_asked_for(path: &std::path::Path) {
    if let Ok(mut held) = summary_reads().lock() {
        held.calls += 1;
        if held.distinct.len() < 100_000 {
            held.distinct.insert(path.to_string_lossy().into_owned());
        }
    }
}

/// `(calls, distinct files)` since the process started.
pub fn summary_read_counts() -> (usize, usize) {
    summary_reads()
        .lock()
        .map(|held| (held.calls, held.distinct.len()))
        .unwrap_or((0, 0))
}
/// Where [`completion`]'s report goes: stderr rather than the default sink, for a client whose stdout is the protocol.
pub fn completion_to_stderr() -> bool {
    static HELD: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
    *HELD.get_or_init(|| is_on(std::env::var_os("CPPLS_TRACE_COMPLETION_STDERR")))
}

/// **A trace that follows one name**, as three of these switches do.
///
/// `CPPLS_TRACE_MACRO=WINAPI_FAMILY` prints that name and no other, because the alternative — printing every macro
/// lookup in an index — is a gigabyte of output. The name is read once for the same reason the switch is: these
/// paths are taken millions of times, and a `String` built per call was measured as part of the cost this module
/// exists to remove.
///
/// `None` means "off", which an unset variable also means; a name is never empty, so an empty value is free to mean
/// the same thing.
macro_rules! named_switch {
    ($($name:ident => $variable:literal, $documentation:literal;)*) => {
        $(
            #[doc = $documentation]
            pub fn $name() -> Option<&'static str> {
                static HELD: std::sync::OnceLock<Option<String>> = std::sync::OnceLock::new();
                HELD.get_or_init(|| {
                    std::env::var_os($variable)
                        .filter(|value| !value.is_empty())
                        .map(|value| value.to_string_lossy().into_owned())
                })
                .as_deref()
            }
        )*
    };
}

named_switch! {
    macro_name => "CPPLS_TRACE_MACRO", "The one macro name to trace, at every lookup the expander makes.";
    guard_name => "CPPLS_TRACE_GUARD", "The one name to trace through every condition evaluation.";
    lookup_name => "CPPLS_TRACE_LOOKUP", "The one name to trace through the walk's macro environment.";
}

#[cfg(test)]
mod tests {
    use super::is_on;

    #[test]
    fn an_unset_variable_is_off_and_so_is_an_empty_one() {
        assert!(!is_on(None));
        assert!(!is_on(Some(std::ffi::OsString::from(""))));
        assert!(is_on(Some(std::ffi::OsString::from("1"))));
        // Anything non-empty counts: these are switches, not settings, and `CPPLS_TRACE_MEMBERS=0` asking for a
        // trace is the same kind of surprise as `0` being false in a shell.
        assert!(is_on(Some(std::ffi::OsString::from("0"))));
    }
}