cpp_code_analysis
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
#ifhave to stay visible, because the reader may be writing the other one; - every edit would invalidate everything, since one
#definechanges 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:
- A stored summary is a promise.
cache::FORMAT_VERSIONmoves 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. - 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 (
viewandview_of_the_file) and are not interchangeable; a macro's name does not exist in the rendering, and a declaration inside a#ifbranch does not exist in the file. - Nothing may guess to avoid saying "not known".
Known::{Yes, No, Unknown(reason)}is deliberate: a caller that getsUnknownis 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
CPPLS_TRACE_TYPES=1
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
docs/cpp-support.md— the language support, feature by feature, and the diagnosticsdocs/memory-status.md— what the analysis holds, measureddocs/module-cache.md— the module index and its cache
License
MIT — see LICENSE.