cpp_code_analysis 0.4.0

The analysis layer of cpp_ls: the preprocessor, symbol scopes, type inference and the semantic checks.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
//! **Navigation and presentation** — classified tokens, selection ranges, folding, signatures, and outline.
//!
//! Moved here from `session/mod.rs` without a change.

use super::*;

impl<F: FileProvider + Clone> Session<F> {
    /// **What each name in this file is** — the classification a semantic highlighter draws colours from.
    ///
    /// Read from the file's own bindings and macro directives, and from the index for a spelling the file does not
    /// declare itself; a name nothing can be said about is left out rather than guessed at. See
    /// [`crate::semantic`] for the four questions, in the order they are asked, and for the measurement behind
    /// asking the index **once per spelling** rather than once per identifier.
    ///
    /// Nothing here is a position question, so the answer does not depend on a cursor — but it does depend on the
    /// index, and a file whose includes have not been read yet answers with **fewer** classifications rather than
    /// with different ones. A caller that publishes these should therefore publish them again once
    /// [`Session::pending`] reaches zero.
    pub fn classified_names(&self, view: &FileView) -> Vec<crate::semantic::Name> {
        use cpp_parser::CppTokenKind;
        let mut names = crate::semantic::classified_names(self.store.index(), view);

        // **The predefined macros, which no file declares.** `__LINE__`, `__FILE__`, `__DATE__`, `__TIME__`,
        // `__cplusplus` and the compiler's own five hundred are defined by the *compiler*, so the walk above — which
        // classifies a name by the declaration it resolves to — has nothing to say about them, and an editor drew
        // `__LINE__` as "standard token type: Other" (reported, with the inspector's own reading). The two tables are
        // this session's: the standard's own (a constant, per language) and the toolchain's `-dM` output.
        //
        // The tokens are the **rendering's**, like the walk's, and this runs before the placement loop for the same
        // reason: a range still in rendering coordinates is what that loop translates.
        let language = self.config_for(&view.path).language_for(&view.path);
        let mut claimed: std::collections::HashSet<usize> =
            names.iter().map(|name| name.range.start_offset).collect();
        for token in view.tree.get_tokens() {
            if token.kind != CppTokenKind::Identifier {
                continue;
            }
            // A predefined macro is spelled with leading underscores on both sides; nothing else in the file needs the
            // two table lookups below.
            let Some(text) = view.get_token_text(token.range) else {
                continue;
            };
            if !text.starts_with('_') {
                continue;
            }
            let start = token.range.start_offset;
            if claimed.contains(&start) {
                continue;
            }
            // **Three sources, because no one of them holds them all**: the standard's constant macros
            // (`__cplusplus`), the standard's position-dependent ones (`__LINE__`, which `-dM` never prints), and the
            // toolchain's `-dM` table (`__GNUC__`). Reported from an editor: `__LINE__ << __FILE__ << __DATE__ <<
            // __TIME__` was drawn as plain identifiers.
            let is_predefined = the_standards_own_macro(text, &language).is_some()
                || a_macro_whose_value_depends_on_the_use(text)
                || self.predefined_macro(text, &view.path).is_some();
            if !is_predefined {
                continue;
            }
            claimed.insert(start);
            names.push(crate::semantic::Name {
                range: token.range,
                kind: crate::semantic::NameKind::Macro,
                declaration: false,
                modifiers: Vec::new(),
                provenance: crate::semantic::Provenance::Macro,
            });
        }

        // **The ranges are moved out of the rendering and into the file, because that is what both consumers read.**
        //
        // The walk reads `view.root`, so every range it answers is an offset in the **rendering** — and the two
        // consumers of this query take it for an offset in the **file**: the semantic-tokens handler computes the
        // client's line and column with `position_in_file(file, name.range.start_offset)` and measures the token with
        // `&file.text[range]`, and `tests/semantic.rs` slices the fixture's own text the same way. Two independent
        // consumers agreeing is the contract; the query was the side that was wrong, and it is user-visible: a colour
        // drawn at an offset the cook shifted is a colour on **another word**.
        //
        // Measured on the suite: `the_header's_class` read `[("l", Function), ("de \"b.", Type), ("\n", Parameter)]`
        // — the tokens of a rendering sliced out of the file. A name whose start the file cannot place is **dropped**,
        // which is the same choice the handler makes one layer up ("dropping one token is the only option that keeps
        // the walk valid"): a name in a region the rendering does not cover — an untaken `#if` branch, the body of a
        // macro — has no file position at all, and keeping it would put a token at an offset that means something else.
        let mut placed = Vec::with_capacity(names.len());
        for mut name in names {
            let Some(start) = view.file_offset_of(ReadingOffset::new(name.range.start_offset))
            else {
                continue;
            };
            let end = view
                .file_offset_of(ReadingOffset::new(name.range.end_offset()))
                .unwrap_or(start);
            name.range =
                cpp_parser::SourceRange::new(start.get(), end.get().saturating_sub(start.get()));
            placed.push(name);
        }
        names = placed;

        // **And the identifiers only the file's own text has.**
        //
        // The walk iterates `view.tree.get_tokens()` — the **rendering's** tokens — so a name the cook removed is not
        // in it at all: an identifier in an untaken `#if` branch, or in the body of a function-like macro. Those are
        // names the reader is looking at, and the module's own words are that this reads "the file's own bindings and
        // macro directives". `a_macro_in_an_untaken_branch_is_still_a_macro` is the test that says so, and it answered
        // `None` against `Some(Macro)`.
        //
        // A parse of the file's own text sees them, **in the file's coordinates already** — so nothing here is
        // translated, and the two passes meet in one numbering. Deduplicated by where the name starts, with the
        // rendering's answer winning: it is the one that carries the macro and binding facts.
        //
        // The guard is "the two readings differ", because a file the cook did not change needs no second pass — and
        // the cost when they do differ is a second walk, which the `Classify` stage timer in
        // `examples/semantic_probe.rs` measures.
        if view
            .written_text()
            .is_some_and(|written| written != &*view.source)
            && let Some(own) = self.view_of_the_file(&view.path)
        {
            // **Where the two passes disagree about one name, the file's own text wins.** Measured both ways: keeping
            // the rendering's answer for a shared start lost `(Parameter, false)` — a use the cook rewrote — and
            // keeping *both* broke `the_classifications_are_sorted_and_disjoint`. A colour is drawn on the reader's
            // text, so for two answers about one offset the one read from that text is the one to draw.
            let mut at_offset: std::collections::HashMap<usize, usize> = names
                .iter()
                .enumerate()
                .map(|(index, name)| (name.range.start_offset, index))
                .collect();
            for name in crate::semantic::classified_names(self.store.index(), &own) {
                match at_offset.get(&name.range.start_offset) {
                    Some(&index) => names[index] = name,
                    None => {
                        at_offset.insert(name.range.start_offset, names.len());
                        names.push(name);
                    }
                }
            }
        }

        // **And the symbol references in the file's documentation comments.** A comment is trivia, so the rendering
        // has none of it and neither walk above sees one — the answer is read from the **written** text, in the file's
        // own coordinates, and each target is resolved with the same query a jump and the hover use
        // (`ProjectIndex::definition`), so the colour, the card and the jump cannot disagree about what a reference
        // names.
        //
        // **Both spellings**, through one reader: a `[`Widget::grow`]` link and a `@see Widget::grow` command's
        // argument. They were two features — and the second was not a feature at all, only an argument the completion
        // mistook for a parameter name — until `crate::doc` made them one question.
        //
        // A target that resolves to nothing is **not** coloured, which is the same answer an identifier the analysis
        // cannot place gets: a colour would say the name is known.
        //
        // Read here rather than in the server's token pass because this is the layer with the index in hand: a
        // spelling in a comment has no tree position to resolve from, and the pass that draws tokens has no session.
        {
            let text: &str = view.written_text().unwrap_or(&view.source);
            for target in crate::doc::targets(text) {
                if !crate::doc::is_a_documentation_comment(text, target.range.start_offset) {
                    continue;
                }
                let spelling = target.spelled_for_a_lookup();
                let kind = self
                    .store
                    .index()
                    .definition(spelling, &view.path)
                    .value()
                    .and_then(|found| {
                        crate::semantic::kind_of_index(crate::index::project::IndexedKind::of(
                            &found.fact,
                        ))
                    })
                    // **A macro is a name too**, and the index holds no *declaration* for one: `[`MAX`]` names a
                    // `#define`, which is a fact about text. The environment the file is compiled in is the same
                    // question the classifier asks for a macro an `#include` brought in, so it is asked rather than
                    // duplicated — and only for a target the index could not describe, which is what keeps a
                    // reference to an ordinary declaration free.
                    .or_else(|| {
                        self.store
                            .index()
                            .macro_names_in_force(&view.path)
                            .contains(spelling)
                            .then_some(crate::semantic::NameKind::Macro)
                    });
                let Some(kind) = kind else {
                    continue;
                };
                names.push(crate::semantic::Name {
                    range: target.range,
                    kind,
                    declaration: false,
                    modifiers: Vec::new(),
                    provenance: crate::semantic::Provenance::Found,
                });
            }
        }

        // **And the code inside a documentation comment's `@code` block**, which is an example rather than prose: its
        // keywords are drawn as keywords and its identifiers resolved the way any other name is. The block is *text*
        // — a comment produces no tokens, so the tree has nothing to say about it — and the lexer that reads it is the
        // same one every other spelling in this project is read by.
        {
            let text: &str = view.written_text().unwrap_or(&view.source);
            for block in crate::doc::code_blocks(text) {
                let body = &text[block.start_offset..block.end_offset()];
                let (tokens, _) = cpp_parser::lex(body, &cpp_parser::LexerConfig::default());
                for token in tokens {
                    let Some(spelling) =
                        body.get(token.range.start_offset..token.range.end_offset())
                    else {
                        continue;
                    };
                    let is_a_keyword = cpp_parser::is_keyword(token.kind);
                    if !is_a_keyword && token.kind != cpp_parser::CppTokenKind::Identifier {
                        continue;
                    }
                    let kind = if is_a_keyword {
                        Some(crate::semantic::NameKind::Keyword)
                    } else {
                        self.store
                            .index()
                            .definition(spelling, &view.path)
                            .value()
                            .and_then(|found| {
                                crate::semantic::kind_of_index(
                                    crate::index::project::IndexedKind::of(&found.fact),
                                )
                            })
                    };
                    let Some(kind) = kind else {
                        continue;
                    };
                    names.push(crate::semantic::Name {
                        range: cpp_parser::SourceRange::new(
                            block.start_offset + token.range.start_offset,
                            token.range.length,
                        ),
                        kind,
                        declaration: false,
                        modifiers: Vec::new(),
                        provenance: crate::semantic::Provenance::Found,
                    });
                }
            }
        }

        // **And re-sorted, because the crossing is not order-preserving.** The walk answers in the rendering's order,
        // and a token a macro produced maps back to *where the macro was invoked* — which can be before a name that
        // preceded it in the rendering. The consumer builds a **delta walk** (`SemanticTokens`, where every token is
        // relative to the one before it), so an out-of-order list does not merely look odd: the deltas would be
        // negative. Sorted here rather than by the caller, because this is where the order stopped being the
        // rendering's.
        names.sort_by_key(|name| (name.range.start_offset, name.range.end_offset()));

        names
    }

    /// **Every format string in this file, with what each part of it is** — see [`crate::format`].
    ///
    /// ```cpp
    /// std::println("值 = {:.3f}", x);    `{:.3f}` is a specifier and `f` a conversion
    /// printf("%-8.2f|%*d", y, w);        a specifier, a conversion, and a width taken from an argument
    /// scanf("%3d %[a-z]", &n, name);     and the scanset
    /// ```
    ///
    /// # Why the *written* reading, and only the written reading
    ///
    /// A colour is painted on the text the reader has in the buffer, and the answers here are **file offsets**. A
    /// rendering's offsets are its own (see [`FileView::file_offset_of`]), and a format string is a *literal*: the cook
    /// never expands one, but it does move everything after the macros it did expand. So this reads
    /// [`Session::view_of_the_file`] and refuses a rendering — the same rule `push_doc_commands` one layer up states
    /// for a comment, and for the same reason.
    ///
    /// # Why the tokens rather than the tree
    ///
    /// The format string is there either way, and where the parser put it is not a question this
    /// pass has an opinion about: the call is "a `(` whose arguments are…", which the token stream
    /// says exactly. See [`crate::format::literals_in`].
    pub fn format_literals(
        &self,
        view: &FileView,
        config: &crate::format::FormatConfig,
    ) -> Vec<crate::format::FormatLiteral> {
        // **A rendering is not this pass's text.** Its tree's tokens are the cook's, and a range in it names a place
        // in a string the reader has never seen.
        if view.written_text().is_some() {
            return Vec::new();
        }

        // **A name the file does not qualify is resolved, and only where it decides something**: `format("…")` after
        // `using namespace std;` is the standard one, and a project's own `format` is not.
        //
        // The instrument is the **binding** and its scope, not `definitions`: that query answers "where do I jump to"
        // and fills `DeclFact::scope` with the qualifier *the cursor wrote*, which for a bare name is no scope at
        // all — measured, a bare `format(…)` resolved to `format` with `scope: None` in both spellings of the using
        // (`using namespace std;` and `using std::format;`). What this needs is the namespace the declaration sits
        // in, which is the scope the binding lives in, and `ScopeTree::qualified_name_of` spells it.
        //
        // A **using-declaration** is the one shape that still answers with the wrong thing: `using std::format;`
        // binds the name to the using-declaration itself (which is where go-to-definition goes), so the spelling
        // resolves to `format` at file scope and is refused. `using namespace std;` is followed properly, and a
        // qualified `std::format(…)` needs neither.
        let mut qualified_name = |offset: usize| -> Option<String> {
            let reading = view.reading_offset_of(FileOffset::new(offset))?;
            let Known::Yes(binding) =
                crate::sema::resolve::definition_at(&view.scopes, &view.root, reading.get())
            else {
                return None;
            };
            let name = binding.name.identifier_text()?;
            Some(match view.scopes.qualified_name_of(binding.scope) {
                Some(scope) if !scope.is_empty() => format!("{scope}::{name}"),
                _ => name.to_string(),
            })
        };

        crate::format::literals_in(
            &view.source,
            view.tree.get_tokens(),
            config,
            &mut qualified_name,
        )
    }

    /// **The ranges to select at a cursor, in the file's own coordinates** — the third fact that belongs to the text
    /// the *reader* is looking at rather than to the text the compiler reads.
    ///
    /// A chain answers in the coordinates of the tree it walks, and every view this session holds is of a
    /// **rendering**. Translating in and out does not repair that: a cursor in whitespace maps *forward* to the next
    /// token — right for a cursor — so a walk of the rendering begins at a token that starts **after** the cursor and
    /// builds a rung that does not contain the position it was built for. Measured: the cursor at file offset 9 in
    /// `namespace ns` produced a chain whose innermost rung began at 10.
    ///
    /// Folding answers the same question the same way for the same reason, and so does documentation for comments.
    /// **Three facts, one rule**: a selection, a fold and a doc comment are things the reader sees in their buffer,
    /// so they are asked of the buffer.
    pub fn selection_chain(
        &self,
        view: &FileView,
        offset: FileOffset,
    ) -> Vec<cpp_parser::SourceRange> {
        let Some(written) = view.written_text() else {
            // No rendering: this view *is* a parse of the file's own text, so its offsets are already the file's.
            return view.selection_chain(ReadingOffset::new(offset.get()));
        };
        let tree = cpp_parser::CppParser::parse(written, cpp_parser::ParserConfig::default());
        crate::file::view::selection_chain_of(&tree.get_red_root(), offset.get())
    }

    /// **The file's foldable regions** — see [`crate::folding`].
    ///
    /// Read from the **buffer's own tokens and directives**, which is the same source the outline uses and for the
    /// same reason: folding is about the file in front of the reader, so an unsaved edit is folded as it is typed,
    /// and a declaration in a branch nobody takes is a region like any other. Nothing here consults the index, the
    /// cooked reading, or any other file — a fold is a fact about this text.
    pub fn folding_ranges(&self, view: &FileView) -> Vec<crate::folding::Fold> {
        // **The file in front of the reader, which is not the text this view parses any more.**
        //
        // The promise above — "the buffer's own tokens and directives" — was free while a view *was* the file's own
        // text: `view.source` and the written text were one string. They stopped being one when the raw parse was
        // deleted and a view became the compiler's reading, and this function was left reading the wrong one. A
        // rendering has no `#include` line, no comment and no `#if` region in it — those are what a preprocessor
        // removes — and it usually has fewer line breaks, so any fold it could still see is thrown away by the rule
        // that a region on one line hides nothing. Measured over the wire: `textDocument/foldingRange` on a
        // four-region fixture answered **`[]`**.
        //
        // Folding is a question about *layout* rather than about meaning — where the braces are, which lines a
        // comment covers, where an `#if` closes — so reading the file's own text is not the "semantic view of
        // unexpanded C++" that was deliberately removed; it is the only text those regions exist in. The lexer runs
        // here rather than being kept because only this query wants these tokens, and only when a client asks.
        let Some(written) = view.written_text() else {
            // No rendering: this view *is* the file's own text, and its tokens are already the right ones.
            return crate::folding::folding_ranges(&view.source, view.tree.get_tokens());
        };
        let (tokens, _) = cpp_parser::lex(written, &cpp_parser::LexerConfig::default());
        crate::folding::folding_ranges(written, &tokens)
    }

    /// **The signatures of the call the cursor is inside** — see [`crate::signature`].
    ///
    /// A list, because a call to an overloaded function has more than one declaration and the protocol's
    /// `SignatureHelp.signatures` is a list: `std::format(` is four of them, and answering one — or none, which is
    /// what this did while the name looked ambiguous — is a popup with nothing in it. The reader picks; this layer
    /// claims nothing about which overload a half-typed argument list means.
    ///
    /// The parameters come from the *callee's* declarations, so a call into a header parses that header for this
    /// answer — **once per file**, however many overloads it holds.
    ///
    /// The documentation above each declaration is read here rather than by the caller: it is the same declaration
    /// the signature came from, and asking twice would be two lookups for one popup.
    /// **The signature of a function-like macro call**, or `None` when the cursor is not inside one.
    ///
    /// A macro is expanded in a rendering, so the call the reader is typing exists only in the file's **own** text —
    /// which is why this takes a view of that text and a **file offset**, and not the rendering-view pair the
    /// function engine takes. `ADD(1, |)` is `((1) + ())` in the rendering: there is no call there to describe.
    ///
    /// A **file offset** rather than a reading offset is the other half of the same fact: mapping a position inside
    /// a macro expansion back to the file is not reliable (the expansion's bytes come from the body, not from the
    /// invocation), and a caller that already has the client's position has the file offset for free.
    pub fn macro_signature_at(
        &self,
        view: &FileView,
        offset: crate::file::coordinates::FileOffset,
    ) -> Option<crate::signature::CallSignature> {
        crate::signature::a_macro_signature(self.store.index(), view, offset.get(), &mut |path| {
            self.view(path)
        })
    }

    pub fn signatures_at(
        &self,
        view: &FileView,
        offset: ReadingOffset,
    ) -> Vec<crate::signature::CallSignature> {
        let mut signatures =
            crate::signature::signatures_at(self.store.index(), view, offset.get(), |path| {
                self.view(path)
            });

        for signature in &mut signatures {
            // **The declaration's offset is the *index's*, and the index reads the cooked rendering.** So
            // `declared_at` is a **reading** offset, while `Session::documentation` looks for the comment in the text
            // the reader **wrote** - and the two differ by exactly what the cook removed, which for a documented
            let declared = self.view(&signature.declared_in);
            let Some(in_the_file) = declared.as_ref().and_then(|declared| {
                declared.file_offset_of(ReadingOffset::new(signature.declared_at))
            }) else {
                continue;
            };
            signature.documentation =
                self.documentation(view, &signature.declared_in, in_the_file.get());
        }

        signatures
    }
}