cpp_code_analysis 0.4.0

The analysis layer of cpp_ls: the preprocessor, symbol scopes, type inference and the semantic checks.
Documentation

cpp_code_analysis

crates.io docs.rs

What the code means. cpp_parser answers what a file looks like; cpp_toolchain answers what the compiler reads; this crate answers the questions a reader asks about it — scopes, declarations, types, members, overloads, modules, and the diagnostics an editor shows.

a rendering, mapped back   ->  the file's declarations              (index, summary)
a name at an offset        ->  a declaration, or why not            (sema::resolve, index::project)
a call                     ->  the overload, and what it returns    (index::project::calls)
a cursor                   ->  members, parameters, a card          (completion, inlay, hover helpers)
a project                  ->  an index, its cache, and a session   (index::store, cache, session)

Entry point for a client is [Session]: it holds the files, the project configuration, the index and its cache, and answers one question at a time without ever blocking the caller on a cook it has not asked for.

Why the preprocessor is a crate below, and not a pass inside this one

The obvious design — preprocess, then parse the output — is what a compiler does, and it is unusable for an editor:

  • the tree has to stay lossless, so expansion produces a shadow token stream (the rendering) and never rewrites the tree;
  • both branches of an #if have to stay visible, because the reader may be writing the other one;
  • every edit would invalidate everything, since one #define changes every file that includes it.

So the rendering is a unit produced below, keyed by its text and its environment, and this crate reads it.

The map

index        the project as one thing: symbols across files, members, definitions, calls, modules, and the cache key
sema         one file's scopes and meanings: resolve, types, declarations, checks, layout, call syntax, deduction
session      the front door: files, configuration, the pump, question-shaped queries, the database
cache        summaries on disk: the key, the store, the reader and the format version
file         one file's view: `FileView`, the coordinate conversions, and the documentation node of a comment

Three contracts worth knowing before changing anything here:

  1. A stored summary is a promise. cache::FORMAT_VERSION moves whenever what a fact says changes — a kind, a spelling, a parameter list — because a summary written by another reader is a wrong answer and not a missing one. Each move carries its own measurement in the constant's documentation.
  2. A question about a position is asked of the rendering; a question about a macro is asked of the file. The two views are different (view and view_of_the_file) and are not interchangeable; a macro's name does not exist in the rendering, and a declaration inside a #if branch does not exist in the file.
  3. Nothing may guess to avoid saying "not known". Known::{Yes, No, Unknown(reason)} is deliberate: a caller that gets Unknown is told which spelling stopped the walk.

Two readings of one expression

A macro invocation has no type in the file's own text and a full type in the rendering, so a type question whose answer is Unknown may be asked again of the rendering — by span, and with the rules recorded in docs/open-questions.md (the MACRO(x)->member round). That crossing is why ci_func(ci)->p answers Proto* on Lua 5.5.0.

Testing

cargo test -p cpp_code_analysis                    # the suites below
CPPLS_TRACE_TYPES=1 cargo test -p cpp_code_analysis --test macro_member_types -- --nocapture
real projects   c_corpus cpp_corpus neovim_probe codestyle_probe real_project_probe lua_source_reports reported_defects
language        types scopes members modules concepts contracts reflection generics layout lifetime checks
reading         cook_fixture_probe cooked rendered_reading rendering_real rendering_scope unit_*_probe expand
cost            allocation_probe memory_probe cold_start_memory_probe namespace_macros slice_probe scale_probe

Real-project tests read a project from the environment and are #[ignore]d (CPPLS_C_PROJECT, CPPLS_PROJECT, CPPLS_LUA_PROJECT, …); the hermetic ones run in CI. docs/open-questions.md is where each of them comes from, with the before/after numbers.

Probes

Every claim in this repository is measured, and the instruments are environment switches documented with what they print in crates/cpp_toolchain/src/probes.rs — CPPLS_TRACE_TYPES, CPPLS_TRACE_MEMBERS, CPPLS_TRACE_INFERENCE, CPPLS_TRACE_ANSWERS, CPPLS_TRACE_VIEW, CPPLS_TRACE_DIAGNOSTICS and the rest, plus CPPLS_NO_INFERENCE and CPPLS_NO_INDEX_LOOKUP for splitting a measurement into the engine and the index.

See also

License

MIT — see LICENSE.