cpp_code_analysis 0.1.4

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
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
//! One file, parsed — what a cursor query is answered against.
//!
//! A query about a *position* needs three things the index does not hold: the file's **text** (the buffer when the
//! user is typing in it), its **scopes** (which declaration a name at an offset means — a summary records facts
//! about declarations, not the syntax a position resolves against), and the **line index** that turns a client's
//! line and column into the byte offset every layer below speaks.
//!
//! ```text
//! FileView {
//!     file        which file in the VFS this is — its identity, not its spelling
//!     path        where it is, for the layers that still speak paths
//!     source      the text, shared: no copy per request
//!     line_index  the index *of that text*, shared, built when the VFS took the file in
//!     tree/root   the parse of it
//!     scopes      the file's scopes, built from the same tree
//!     open        did the text come from an editor buffer?
//! }
//! ```
//!
//! # Why it borrows nothing
//!
//! A view is the VFS's entry plus a parse, and the two shared halves are `Arc`s — so a view **outlives the call
//! that made it** without holding a lock or a borrow of the session. That is what a request needs: the handler
//! resolves a position, asks several questions about one file, and hands a location back to the client, all while
//! other requests read the same session.
//!
//! # Why the line index is not derived here
//!
//! It used to be: `offset_at` built a `LineIndex` per call, which is a **scan of the whole file** for every
//! position a client asked about — the wrong side of the boundary, because the file's lines change exactly when its
//! text does, and the VFS is what knows about that. See [`crate::file::vfs`]: the text and its index are made
//! together and replaced together, so a view's index can never be one edit behind its text.

use std::path::PathBuf;
use std::sync::Arc;

use cpp_parser::{CppDocComment, CppParseError, CppSyntaxNode, CppSyntaxTree, LineIndex};

use crate::file::coordinates::{FileOffset, ReadingOffset};
use crate::file::paths::FileId;
use crate::file::vfs::VfsFile;
use crate::symbol::ScopeTree;

/// **A file's own text, lexed — and deliberately not parsed.**
///
/// This is what a question about the **text** is answered from: a fold, a selection range, a bracket, a highlight,
/// the span of a diagnostic, the bytes a rename would edit. Returned by [`crate::Session::tokens_of`].
///
/// # Why it has no tree
///
/// Because C++ source with its macros unexpanded **is not a program**. The tree a grammar builds from it is shaped
/// like a syntax tree and means nothing as one — measured on MSVC's headers, `<xutility>` has 84 error nodes read as
/// written and **0** read after preprocessing, `<xstring>` 17 against 0 (`examples/cooked_parse.rs`). A struct that
/// carried that tree would be handed to a caller that would eventually ask it what a name means.
///
/// So the type is the boundary: **tokens and positions, no declarations and no scopes.** A caller that needs
/// meaning has one route — [`crate::Session::view`], which answers from a rendering, and answers `None` while there
/// is none so that the caller defers instead of guessing.
///
/// The lexer is the parser's own ([`cpp_parser::lex`]), so a token here begins and ends exactly where the parser's
/// does; there is one token stream in this crate and this is not a second one.
#[derive(Debug, Clone)]
pub struct TokensOf {
    /// The file this is about.
    pub path: PathBuf,
    /// The file's own text. Every offset in this struct is an offset into this.
    pub source: Arc<str>,
    /// The line index of [`TokensOf::source`], shared with the VFS rather than rebuilt.
    pub line_index: Arc<LineIndex>,
    /// Did the text come from an open buffer rather than from the file?
    pub open: bool,
    /// Every token of the text, in order. They cover the file byte for byte, so concatenating their text reproduces
    /// `source` — which is what makes a range built from two of them a range in this file.
    pub tokens: Vec<cpp_parser::CppTokenData>,
}

impl TokensOf {
    /// The token containing an offset, if one does. Whitespace and newlines are tokens too, so this answers for any
    /// offset inside the file.
    pub fn token_at(&self, offset: ReadingOffset) -> Option<&cpp_parser::CppTokenData> {
        let offset = offset.get();
        self.tokens
            .iter()
            .find(|token| token.range.start_offset <= offset && offset < token.range.end_offset())
    }

    /// The text of a range, and `None` when it is not inside this file.
    ///
    /// A convenience over indexing `source`, because that is what every lexical caller does with a range and the
    /// bounds check is the part that gets forgotten.
    pub fn text_of(&self, range: cpp_parser::SourceRange) -> Option<&str> {
        self.source.get(range.start_offset..range.end_offset())
    }

    /// A **line and column** to a byte offset, both counted from zero.
    ///
    /// The mapping a client's positions need, and the one place LSP's own rule is *not* implemented: the columns this
    /// counts are characters, while the protocol counts UTF-16 code units, and the two differ on a line with an emoji
    /// or any character outside the basic plane. That conversion is the protocol layer's — doing it here would put a
    /// rule about a wire format in the crate that has no wire format.
    ///
    /// A lookup in the index the VFS already built: no scan, and no way for the answer to be about a different text
    /// than the one it was built from.
    pub fn offset_at(&self, line: usize, column: usize) -> Option<ReadingOffset> {
        self.line_index
            .get_offset(line, column, &self.source)
            .map(|at| ReadingOffset::new(usize::from(at)))
    }

    /// A byte offset back to a **line and column** — the inverse of [`TokensOf::offset_at`], and the direction a
    /// diagnostic needs: a position is what a client is told.
    ///
    /// A position past the end of the text answers `None` rather than clamping: an offset that is not in the file is
    /// a caller's mistake, and a range built from a clamped one would point at the wrong code.
    pub fn position_at(&self, offset: ReadingOffset) -> Option<(usize, usize)> {
        let offset = offset.get();
        self.line_index.position_of(offset, &self.source)
    }

    /// The text, for a caller that wants a `&str` rather than the shared handle.
    pub fn source(&self) -> &str {
        &self.source
    }
}
/// A file in the VFS, parsed, with its scopes.
#[derive(Debug, Clone)]
pub struct FileView {
    /// The file's identity inside the VFS — stable across spellings of its path, and what the view is *of*.
    pub file: FileId,
    pub path: PathBuf,
    /// The text analysed: the buffer when open, the file otherwise. Shared with the VFS, so a view costs a pointer.
    ///
    /// **This is the *reading*, and the two are not always the same text.** For a view of a file's own tokens they
    /// are the file, and every offset in this struct is a file offset. For a view of a **rendering** — what a
    /// preprocessor produced, which is what a compiler's parser is handed — they are the rendering, and the offsets
    /// are the rendering's; [`FileView::file_offset_of`] and [`FileView::reading_offset_of`] are the way between the
    /// two, and [`FileView::written`] is the text on the other side.
    pub source: Arc<str>,
    /// The line index **of [`FileView::source`]** — the same one the VFS built when it took this text in.
    pub line_index: Arc<LineIndex>,
    /// The parse of [`FileView::source`], kept because a caller may want the diagnostics or the token list.
    pub tree: CppSyntaxTree,
    /// The tree's root. Exactly `tree.get_red_root()`, kept because every query wants it and re-deriving a red root
    /// per query would allocate one per query.
    pub root: CppSyntaxNode,
    /// The file's scopes, built from the same tree.
    pub scopes: ScopeTree,
    /// Did the text come from an open buffer rather than from the file?
    pub open: bool,
    /// **The file's own text, when [`FileView::source`] is a rendering of it.**
    ///
    /// `None` — the ordinary case, and every view until a rendering one existed — means the two are the same text
    /// and the mapping below is the identity.
    written: Option<Arc<str>>,
    /// **The line index of [`FileView::written`]** — the file's own, which is the one a client's positions are in.
    ///
    /// Kept beside the written text rather than derived per request: a line index is a scan of the whole file, a
    /// file with a rendering is a standard-library header of a hundred thousand lines, and a client asks about a
    /// position on every keystroke.
    written_lines: Option<Arc<LineIndex>>,
    /// **One entry per token of the stream the rendering was made from**, in the same order, each saying where the
    /// spelling is in the rendering and where to act on it in the file.
    ///
    /// Empty exactly when [`FileView::written`] is `None`. It is an `Arc<[_]>` rather than a `Vec` because a view is
    /// cloned per request — every handler takes one — and a header's rendering is hundreds of thousands of tokens.
    reading: Arc<[crate::preprocess::cooked::RenderedSpan]>,
}

impl FileView {
    /// **Where in the file's own text the token at `in_the_reading` was written.**
    ///
    /// The question a client's position has to be answered in: a rendering's offsets are its own, and an editor
    /// speaks the file's. `None` — no rendering, or an offset past the end — means the identity, because a view of
    /// a file's own tokens has one coordinate system and it is the file's.
    ///
    /// The span's [`reported`](crate::preprocess::cooked::RenderedSpan::reported) rather than its
    /// [`written`](crate::preprocess::cooked::RenderedSpan::written), and the choice is the whole of what a reader
    /// means by "here": a token a macro produced was *written* in the header that defines the macro and *acts*
    /// where the macro was invoked, and a client shown the header would be shown a place its own buffer does not
    /// contain.
    pub fn file_offset_of(&self, in_the_reading: ReadingOffset) -> Option<FileOffset> {
        let in_the_reading = in_the_reading.get();
        if self.written.is_none() {
            return Some(FileOffset::new(in_the_reading));
        }
        Some(FileOffset::new(
            self.span_at(in_the_reading)?.reported.start_offset,
        ))
    }

    /// **Where in the file a *range's end* is** — the outbound mapping for the far end of a range.
    ///
    /// [`FileView::file_offset_of`] answers with the span **containing** an offset, so an end that falls in
    /// whitespace walks forward to the next token: a finding about the value `123` in `std::string x = 123;` came
    /// out covering the rest of the line, because the end of the expression is followed by a `;` and a newline that
    /// the *next* span owns. A range's end is the end of the **last byte the range covers**, which is what this
    /// asks for — and it is a separate method rather than a flag because the two ends of a range are two different
    /// questions, which is the lesson this crate keeps relearning.
    pub fn file_offset_of_end(&self, in_the_reading: ReadingOffset) -> Option<FileOffset> {
        let in_the_reading = in_the_reading.get();
        if self.written.is_none() {
            return Some(FileOffset::new(in_the_reading));
        }
        if in_the_reading == 0 {
            return Some(FileOffset::new(0));
        }

        // **Position-preserving inside the span, not "the span's end".** A span's reported range covers the trivia
        // that rides with the text it stands for, so answering with its end made a range one byte too long: measured
        // on `if (x = 1) { … }`, the condition's end mapped from 35 to 36 and a finding about `"(x = 1) "` came out
        // quoting `"(x = 1) {"` — which is the "the range covers the whole line" a reader sees, and the reason the
        // guard that checks a finding is about this file's own text was dropping every finding of this check.
        //
        // The end of a range is the position just past its last byte, so the answer is the span's start plus however
        // far into the span that last byte is: exact for a span that maps one byte to one byte, and for a span that
        // maps a macro's expansion it lands one byte past the invoked token, which is where the reader sees it.
        let last = self.span_at(in_the_reading - 1)?;
        let into_the_span = (in_the_reading - 1).saturating_sub(last.cooked.start_offset);
        Some(FileOffset::new(
            last.reported.start_offset + into_the_span + 1,
        ))
    }

    /// **A whole range of the reading, as the range of the file a reader would point at.**
    ///
    /// The companion of [`FileView::file_offset_of`], and separate from it for the reason a range is not two
    /// offsets: a macro's expansion reports **one** position for each of its tokens — the invocation — so mapping a
    /// range end by end collapses anything built from a body onto that one spot.
    ///
    /// The answer is the **bounding range of every span the range covers**. A range entirely inside a macro body
    /// therefore maps to the whole invocation, which is the text a reader can see and fold; a range the file wrote,
    /// with a macro's argument in the middle, maps to itself with the argument's call site in place.
    ///
    /// `None` when no span covers the range — the spans tile the rendering, so a gap is text the cook produced
    /// rather than text anyone wrote. See [`FileView::was_written_here`], which relies on the same tiling.
    pub fn file_range_of(
        &self,
        in_the_reading: cpp_parser::SourceRange,
    ) -> Option<cpp_parser::SourceRange> {
        if self.written.is_none() {
            return Some(in_the_reading);
        }

        let mut bounds: Option<(usize, usize)> = None;
        for span in self
            .reading
            .iter()
            .skip_while(|span| span.cooked.end_offset() <= in_the_reading.start_offset)
            .take_while(|span| span.cooked.start_offset < in_the_reading.end_offset())
        {
            let reported = &span.reported;
            bounds = Some(match bounds {
                Some((start, end)) => (
                    start.min(reported.start_offset),
                    end.max(reported.end_offset()),
                ),
                None => (reported.start_offset, reported.end_offset()),
            });
        }

        let (start, end) = bounds?;
        Some(cpp_parser::SourceRange::new(
            start,
            end.saturating_sub(start),
        ))
    }

    /// **Was this range of the reading written in this file?**
    ///
    /// The cook already knows, per token: [`RenderedSpan::written`] is `Some` where the file wrote the spelling and
    /// `None` where it came from a macro body belonging to another file. A check runs over a **rendering** — a header
    /// inlined where its `#include` was — so a node it finds may belong to another file entirely, and a finding about
    /// it would be drawn where the reader cannot see the text: measured, on the `#include` line itself.
    ///
    /// A range that no span covers answers `false`: the spans tile the rendering, so a range between them is text
    /// the cook produced rather than text the file wrote, and "not this file's" is the honest answer for it.
    pub fn was_written_here(&self, in_the_reading: cpp_parser::SourceRange) -> bool {
        if self.written.is_none() {
            return true;
        }
        let mut covering = self
            .reading
            .iter()
            .skip_while(|span| span.cooked.end_offset() <= in_the_reading.start_offset)
            .take_while(|span| span.cooked.start_offset < in_the_reading.end_offset());
        let mut any = false;
        for span in covering.by_ref() {
            any = true;
            if span.written.is_none() {
                return false;
            }
        }
        any
    }
    /// **Where in the rendering the file's own offset `in_the_file` is acted on.**
    ///
    /// The other direction, and the one a client's position needs: an editor sends a line and a column in the file,
    /// and every layer below this struct speaks the reading. `None` when the offset is in a region the rendering
    /// does not contain — a `#if` branch nobody takes, a comment — which a caller must read as "no answer here"
    /// rather than as an offset of zero.
    pub fn reading_offset_of(&self, in_the_file: FileOffset) -> Option<ReadingOffset> {
        let in_the_file = in_the_file.get();
        if self.written.is_none() {
            return Some(ReadingOffset::new(in_the_file));
        }
        // **A token the file wrote is found by where it was _written_, not by where it reports.**
        //
        // The two fields answer different questions and this lookup was asking the wrong one. `reported` is where a
        // token should be *shown* — and for anything a macro produced that is the **outermost call site**, which is
        // the text the reader can see. `written` is where the token actually sits in this file, and it is `Some` for
        // exactly the tokens this file spelled: including **a macro's arguments**, which the file writes in full and
        // the expansion copies.
        //
        // Reading `reported` therefore lost the cursor inside a macro's argument: every span of the expansion reports
        // the call site, so the first one at or after the cursor was a token of the *outer* call. Measured on
        // `PICK(1, scale(2, |))` with `#define PICK(first, second) pick_impl((first), (second))`: the file offset 154
        // (just before `scale`'s closing parenthesis) mapped to **63**, while `scale(2, )` occupies 69..79 of the
        // rendering — the cursor landed before the call it was inside, `call_around` answered the enclosing
        // `pick_impl`, and signature help had no declaration to answer with.
        //
        // The written search comes first and the reporting one still follows it, because they are both right about
        // their own positions: a cursor on a `#define` line, or inside text a macro produced and this file did not
        // write, has no written span and keeps the answer it had.
        let span = self
            .reading
            .iter()
            .find(|span| {
                span.written.as_ref().is_some_and(|written| {
                    written.start_offset <= in_the_file && in_the_file < written.end_offset()
                })
            })
            .or_else(|| {
                self.reading
                    .iter()
                    .find(|span| span.reported.end_offset() > in_the_file)
            })?;

        // **A cursor exactly after a token, with deleted text after it, is still after that token.**
        //
        // The commonest position a completion is asked at is the one a keystroke leaves the caret in: `auto x = a|`.
        // The newline that follows it produced no token, so the cursor is in a *gap* — and the gap rule below
        // answers with the **next** token's start, which here is `return` on the next line. Everything downstream
        // then reads the position as "a name has not been typed": the list came back unfiltered (`a|` offered every
        // name in scope), narrower (`an|` offered only the keywords, because the prefix had become the last `n`), and
        // accepting an item wrote `a` + `anotherVec` — the item's replace range was empty, so the client inserted
        // after the letter already there.
        //
        // The rule is deliberately exact — the cursor must sit **at the end of a token's written range**, with no
        // file bytes of its own — so a caret on a blank line, or in the middle of a comment, keeps the answer it had.
        if let Some(previous) = self
            .reading
            .iter()
            .rev()
            .find(|span| span.reported.end_offset() == in_the_file)
        {
            return Some(ReadingOffset::new(previous.cooked.end_offset()));
        }

        // **A cursor in a gap is a question about the text that was deleted, and the answer is not the next token.**
        //
        // The spans do not tile the file: a comment, a `#define`, an `#include` line and the branch of an `#if`
        // nobody takes all produce no tokens, so there are gaps between one span's *reported* end and the next one's
        // start. Measured:
        //
        // ```text
        //   file    "int f() { // a note\n    return 0;\n}\n"   (36 bytes)
        //   reading "int f() { return 0; }"                      (21 bytes)
        //   cursor 14, inside the comment  ->  Some(10), where the rendering has "return"
        // ```
        //
        // The answer is the **start of the token the cursor is nearest**, which is what this mapping meant before the
        // note above existed. `None` was tried for the gap and made the suite worse (13 passing → 12): a caller with
        // no offset has no answer to give, while a caller at the token's start has one it can then refuse. Refusing
        // at the *query* — "is this position in a comment" — is where that belongs, and it is already asked there.

        // **How far into the token the cursor is, carried across.** Returning the token's start loses it, and the
        // loss is not cosmetic: a cursor five bytes into `local_variable` arrives at the *first* byte of the token,
        // where a completion reads "nothing has been typed" and answers an unfiltered list. Measured on the
        // completion fixture:
        //
        // ```text
        //   cursor: file 112 -> reading 80   (the same spot is 85 in the rendering)
        //   the token starts at 107 in the file and 80 in the rendering
        //   the two cursors differ by 32; the two token starts differ by 27
        // ```
        //
        // The token start mapped correctly (107 → 80) while the cursor inside it did not.
        //
        // The offset is only meaningful when the file **wrote** the token: then `written` and `cooked` cover the same
        // spelling byte for byte, so a position inside one is the same distance inside the other. For a token a
        // macro produced there is no such correspondence — `written` is `None` and the answer stays the token's
        // start, which is where the expansion begins and where a cursor in that region belongs.
        let inside = match span.written {
            Some(written) if written.start_offset <= in_the_file => {
                in_the_file - written.start_offset
            }
            _ => 0,
        };
        // **A position the rendering does not have is not a position.** The rendering is shorter than the file
        // whenever a directive's text produced no tokens — a `#include` line is replaced by the header's, a `#define`
        // by nothing — so a cursor near the file's end can map past the rendering's. Returning it anyway makes every
        // caller walk a tree that does not reach there, which is a panic inside `rowan` rather than an answer:
        // measured, `Bad offset: range 0..106 offset 126` on the completion fixture, where the cursor sits just past
        // `w.` and the rendering is 106 bytes. `None` is this function's documented way of saying "no answer here".
        let mapped = span.cooked.start_offset
            + inside.min(span.cooked.end_offset() - span.cooked.start_offset);
        (mapped <= self.source.len()).then(|| ReadingOffset::new(mapped))
    }

    /// The span whose spelling covers `in_the_reading`, by binary search.
    ///
    /// The spans are in stream order, so their `cooked` ranges are sorted and do not overlap — which is what makes
    /// this a search rather than a scan. A rendering of a standard-library header is a few hundred thousand tokens
    /// and a query about a position is answered per keystroke, so a scan would be the wrong shape.
    fn span_at(&self, in_the_reading: usize) -> Option<&crate::preprocess::cooked::RenderedSpan> {
        let at = self
            .reading
            .partition_point(|span| span.cooked.end_offset() <= in_the_reading);
        self.reading.get(at)
    }

    /// **The file's own text**, when this view is of a rendering of it.
    ///
    /// `None` for a view of the file's own tokens, where [`FileView::source`] is already that text. A consumer needs
    /// it for the one thing the rendering cannot answer: showing the reader the lines **they wrote**, with the macro
    /// still in them, rather than the expansion the compiler read.
    pub fn written_text(&self) -> Option<&str> {
        self.written.as_deref()
    }

    /// **The line index of the text a document is edited in** — the file's own when this view is of a rendering,
    /// and the rendering's own otherwise.
    ///
    /// The one a caller that turns an offset into a line and a column must use, because that pair is what a client
    /// sees. Paired with [`FileView::written_text`], which is the text the index belongs to: passing one without the
    /// other gives a line number from a different document.
    pub fn written_lines(&self) -> &LineIndex {
        self.written_lines
            .as_deref()
            .unwrap_or(self.line_index.as_ref())
    }

    /// **The byte offset in the file's own text for a line and column** — the first half of what a client's position
    /// needs.
    ///
    /// The line index is the file's own, which is why this is a method on the view rather than arithmetic at the call
    /// site: a view of a rendering holds **two** line indexes, and a caller that reaches for the wrong one gets a
    /// line number from a different document — a wrong answer rather than a missing one. The column is in
    /// **characters**, not bytes and not UTF-16; the conversion from the protocol's unit is the caller's, and
    /// `crate::util::position` is where it happens.
    pub fn file_offset_at(&self, line: usize, column: usize) -> Option<FileOffset> {
        match (&self.written, &self.written_lines) {
            (Some(text), Some(index)) => index
                .get_offset(line, column, text)
                .map(|at| FileOffset::new(usize::from(at))),
            // The ordinary case: one text and one index, and it is already the file's.
            _ => self
                .offset_at(line, column)
                .map(|at| FileOffset::new(at.get())),
        }
    }
}

/// **The documentation of what is declared at `offset`** — the comment a hover shows above a declaration.
///
/// The token's ancestors are asked, innermost first, because a cursor can be anywhere on a declaration: on the
/// name, on the type, on a `*`, on the `;`. Asking every ancestor is what makes the answer the same for all of
/// them, and it cannot answer with the *wrong* node: a node inside a declarator has no documentation of its own —
/// a comment is a sibling of the declaration, see [`cpp_parser::documentation_of`] — and that accessor verifies
/// every candidate against the forward rule, so only the node the comment actually documents matches.
///
/// The comment is returned as the parser's own node rather than as text: delimiters, line markers and `@param` are
/// the documentation layer's reading, and a rendering here would be a second implementation of it.
pub fn documentation_at(root: &CppSyntaxNode, offset: usize) -> Option<CppDocComment> {
    let ancestors = match cpp_parser::token_at(root, offset) {
        Some(token) => token.parent_ancestors().collect::<Vec<_>>(),
        // No token at that offset (past the end of the file): the node walk still answers, and the root always has
        // a range.
        None => root.ancestors().collect(),
    };

    ancestors
        .into_iter()
        .find_map(|node| cpp_parser::documentation_of(&node))
}

/// Could a comment be attached to the construct at `offset` in `text`?
///
/// A **filter, not a reading.** It exists so that a question about a declaration in a file this session has not
/// parsed does not parse a whole header to find out that the declaration has no documentation — and it is only
/// ever allowed to be *too permissive*: `false` is final, `true` means the parse decides.
///
/// Which is why it is loose on purpose. It walks up over the lines a comment can be separated from a declaration
/// by — blank lines and preprocessor directives, both of which the parser's own rule steps over — and accepts a
/// line that starts a line comment or that holds the end of a block comment. A `////` banner, a string literal
/// containing `*/`, a comment that turns out to document something else: each costs one parse, and the other
/// mistake is not symmetric — a `false` where a comment is would lose the documentation silently.
/// **Is the offset inside a comment or a literal in this text?** — a question about the file the reader sees, because
/// a rendering has none of them: a comment is removed before the parse and a literal's spelling can differ.
///
/// A lexer pass rather than a parse: the answer is a token kind, and the tokens of the written text are the only
/// thing needed to say what a cursor is sitting in.
pub fn in_prose(text: &str, offset: usize) -> bool {
    let (tokens, _) = cpp_parser::lex(text, &cpp_parser::LexerConfig::default());
    // **The token the cursor is in, or the one it sits just after.** A client's cursor is *between* two bytes, so a
    // cursor at the end of `// a note` — exactly where it lands after typing one — is not inside the comment by
    // `start <= at < end`; that test finds the token *after* it, which is the newline, and the answer was "not prose".
    // Measured: `a_comment_and_a_literal_offer_nothing` still offered the file's names.
    let at = tokens
        .iter()
        .find(|token| token.range.start_offset <= offset && offset < token.range.end_offset())
        .or_else(|| {
            tokens
                .iter()
                .find(|token| token.range.end_offset() == offset)
        });
    at.is_some_and(|token| {
        matches!(
            token.kind,
            cpp_parser::CppTokenKind::LineComment
                | cpp_parser::CppTokenKind::BlockComment
                | cpp_parser::CppTokenKind::StringLiteral
                | cpp_parser::CppTokenKind::CharLiteral
        )
    })
}

pub fn might_be_documented(text: &str, offset: usize) -> bool {
    let before = text
        .get(..offset.min(text.len()))
        .unwrap_or_default()
        .trim_end();

    // A block comment on the same line as the declaration: `/** Doc. */ int x;`.
    if before.ends_with("*/") {
        return true;
    }

    // **The offset's own line is not evidence — unless it *is* the evidence.** The walk below reads the last line
    // before the offset; inside a declaration that line is the declaration's own text, so a comment above it is never
    // reached: `"/// Doc.\nint x;\n"` asked at the `n` of `int` reads `"i"` and answers `false`, which this filter's
    // contract forbids (`false` is final). Dropping the partial line is the repair — **and only when it is code**: a
    // cursor at the indentation of a commented member (`    /// The n.\n    int n;` asked at the `n` of `int`) has the
    // *comment itself* as its last line, and dropping that line walks past the comment and answers `false` for a
    // declaration that is documented.
    //
    // Measured, and it is the whole of a net loss that stood for two rounds: dropping unconditionally fixed
    // `every_offset_of_the_declaration_reports_it` and `the_declarations_documentation_travels_with_the_signature`
    // and lost `a_member_is_not_documented_by_the_class_comment`,
    // `a_member_documented_by_a_nested_comment_is_found_too` and `the_check_never_rejects_a_comment_the_parser_finds`
    // (25 passing assertions against 24). The three ask at offsets whose last line is `    /// The n.` — the trace
    // this was found with reads:
    //
    // ```text
    // GUARD text_len 55 offset 15 at_line_start true  last_line "/// The class."
    // GUARD text_len 55 offset 45 at_line_start false last_line "    /// The n."
    // ```
    let at_a_line_start = offset == 0 || text.as_bytes().get(offset - 1) == Some(&b'\n');
    let last_line = before.lines().last().unwrap_or_default().trim();
    let the_last_line_is_evidence =
        at_a_line_start || last_line.starts_with("//") || last_line.contains("*/");
    let before = if the_last_line_is_evidence {
        before
    } else {
        match before.rfind('\n') {
            Some(newline) => before[..newline].trim_end(),
            // No line above at all: nothing to drop, and the walk below still has a question to answer — a comment
            // at the *end* of this very line (`int x; ///< The x.`) is one it finds.
            None => before,
        }
    };

    // **A declaration may be written over several lines before the name**, and its comment sits above the whole
    // of it:
    //
    // ```cpp
    //   /**
    //    *  @brief  Write a newline and flush the stream.
    //    */
    //   template<typename _CharT, typename _Traits>
    //     inline basic_ostream<_CharT, _Traits>&
    //     endl(basic_ostream<_CharT, _Traits>& __os)
    // ```
    //
    // Asked at `endl`, the first non-blank line above is `inline basic_ostream<…>&` — not a comment — and the old
    // answer was `false`, which this filter's contract makes *final*: hovering `endl` in `<ostream>` showed no
    // documentation while the comment above it said exactly what the reader wanted. The walk therefore continues
    // over the declaration's own head and stops where a comment would belong to something else: at the end of the
    // previous declaration (`;`, `{`, `}`).
    let mut rest = before;
    for _ in 0..12 {
        let line = match rest.rfind('\n') {
            Some(newline) => &rest[newline + 1..],
            None => rest,
        };
        let line = line.trim();

        if !line.is_empty() && !line.starts_with('#') {
            if line.starts_with("//") || line.contains("*/") {
                return true;
            }

            // The head of this declaration is over, so a comment above it belongs to another one.
            if line.ends_with(';') || line.ends_with('{') || line.ends_with('}') {
                return false;
            }
        }

        // Only blank, directive and declaration-head lines so far: the previous line.
        match rest.rfind('\n') {
            Some(newline) => rest = &rest[..newline],
            None => return false,
        }
    }

    false
}

impl FileView {
    /// Parse a file the VFS is holding, and build its scopes.
    ///
    /// The one constructor, and it takes a [`VfsFile`] rather than text so that a view cannot be made from text
    /// that has no index — the two arrive together or not at all.
    ///
    /// # The scopes are built with **no macro evidence**, and that is an answer rather than a gap
    ///
    /// A view is a buffer and its index entry; `_STD_BEGIN`'s replacement list is in a header, and nothing here has
    /// read the include graph. So this file's scopes claim exactly what this file's tokens say — which is the same
    /// reading [`crate::build_scopes`] produced before the evidence parameter existed. Declarations reached
    /// *through* a query come from their own files' summaries, where the reading was made with the closure in hand,
    /// so `std::vector` still resolves from a buffer that never mentions `std`.
    /// **`None`, by design — see the module note. There is no view of unexpanded text.**
    ///
    /// This used to build a tree and a scope tree by parsing the file's own bytes, and it was wrong at the root:
    /// C++ source with its macros unexpanded **is not a program**, so what came out was a tree shaped like a
    /// syntax tree and meaningless as one. Measured, `examples/cooked_parse.rs`, MSVC's headers:
    ///
    /// ```text
    ///   <xutility>     raw 84 error node(s)   cooked 0     (1 095 871 bytes, 77 files stitched)
    ///   <memory>       raw  8                 cooked 0
    ///   <xstring>      raw 17                 cooked 0
    ///   <utility>      raw 12                 cooked 0
    /// ```
    ///
    /// A caller that needs to **mean** something about a name must have a rendering
    /// ([`FileView::parse_rendering`], reached through [`crate::Session::view`]) — and a caller that has no rendering
    /// must **defer its answer**, not answer from this. A caller that needs a *position*, a token, a fold or a
    /// bracket wants [`crate::Session::tokens_of`], which is lexical and makes no claim about meaning.
    ///
    /// Kept as a function that answers `None` rather than deleted, so that the boundary is a place in the code with
    /// an explanation attached instead of a constructor that a future caller finds and uses.
    #[deprecated(
        note = "there is no semantic view of unexpanded text; use Session::view for meaning \
                         (and defer when it answers None) or Session::tokens_of for positions"
    )]
    pub fn parse(file: &VfsFile) -> Option<FileView> {
        let _ = file;
        None
    }

    /// **The same reading, with the macros the file's includes define.**
    ///
    /// The note above says a view has no macro evidence because "nothing here has read the include graph" — and
    /// that is true of a view made from a [`VfsFile`] alone. A view made **by a session** is a different
    /// situation: the closure is in its index, so the bodies are one lookup away, and handing them over is what
    /// turns
    ///
    /// ```cpp
    /// _STD addressof(*p)          // to a reader of this file: a name, then a call
    /// _MY_BEGIN struct thing {};  // to a reader of this file: two names and a brace
    /// ```
    ///
    /// into the qualified name and the namespace a compiler sees. `_STD` is `::std::` (`yvals_core.h:1906`) and
    /// `_STD_BEGIN` is `namespace std {`, so the difference is not cosmetic: the first makes a name resolve and the
    /// second is the only thing that says **which scope** a declaration belongs to.
    ///
    /// # Both readers get the same value
    ///
    /// The parse reads it through `ParserConfig::with_macros_from_includes` and the scope walk through
    /// [`MacroBodies`](crate::MacroBodies) — the two consumers [`crate::index::FileIndexer`]'s note describes,
    /// given one environment so they cannot disagree. That is the same arrangement the indexer uses; this is the
    /// constructor for callers that have an environment but not a `FileIndexer`.
    /// # The scope walk is what is wired, and the parse is not
    ///
    /// The two readers a body reader can serve are the **parse** and the **scope walk**, and
    /// [`crate::index::FileIndexer`]'s note describes giving one value to both. This constructor gives it to both.
    ///
    /// # Why the offsets are right here and were not before
    ///
    /// [`crate::index::FileIndexer`] carries a warning against passing an environment to a parse — "the version
    /// that passed a positional environment here was answering a *stream* offset against a *file* timeline" — and
    /// the warning is about a **`MacroView`**, the timeline of a unit, whose events carry `at` in each event's own
    /// file's coordinates (see `crate::summary::MacroView::applies_here`). Those are two different rulers and
    /// comparing them is the trap.
    ///
    /// The environment this constructor takes is the other kind: `macros_from_the_closure_with_bodies` builds
    /// [`cpp_parser::IncludedMacro::from_offset`] as **the end of the `#include` that brought the definition in**,
    /// which is an offset in *this* file — the same ruler the parse is reading with. So "is `_STD` a macro here" is
    /// answerable, and answerable correctly.
    /// [`FileView::parse_with`] for a **CUDA** unit — the flag comes from the session's configuration, because a view
    /// of a `.cu` file (or of a header included by one) must read the placement qualifiers and the launch brackets the
    /// same way the indexer did. Two readings of one file that disagreed about whether `k<<<1, 1>>>()` is a call would
    /// be two answers to every question asked about it, and the session's is the one the editor shows.
    pub fn parse_with_cuda(
        file: &VfsFile,
        macros: &cpp_parser::MacroEnvironment,
        cuda: bool,
    ) -> FileView {
        let source = file.text.clone();
        let config = cpp_parser::ParserConfig::default()
            .with_cuda(cuda)
            .with_macros_from_includes(macros);
        let tree = cpp_parser::CppParser::parse(&source, config);
        let root = tree.get_red_root();
        let scopes = crate::sema::scopes::build_scopes(&root, macros);

        FileView {
            file: file.id,
            path: file.path.clone(),
            source,
            line_index: file.line_index.clone(),
            tree,
            root,
            scopes,
            open: file.open,
            written: None,
            written_lines: None,
            reading: Arc::from(Vec::new()),
        }
    }
    pub fn parse_with(file: &VfsFile, macros: &cpp_parser::MacroEnvironment) -> FileView {
        Self::parse_with_cuda(file, macros, false)
    }

    /// **A view of what the preprocessor produced**, rather than of the file's own tokens.
    ///
    /// This is the reading a compiler's parser is handed, and the reason it is worth having one of: a parser given
    /// a rendering never sees a macro invocation at all — `_STD` is `::std::`, `_STD_BEGIN` is `namespace std {` —
    /// so every rule in the grammar that exists to guess which identifier is a macro has nothing to do here. The
    /// scopes are built with [`crate::NoMacroBodies`] for exactly that reason: there is no body to consult, because
    /// the body has already been read.
    ///
    /// # The two coordinate systems
    ///
    /// The offsets in this view — in the tree, in the scopes, in the line index — are the **rendering's**, and the
    /// rendering is not the file: a macro that expands to twenty tokens makes everything after it sit twenty
    /// positions further along. [`FileView::file_offset_of`] and [`FileView::reading_offset_of`] are the way
    /// between the two, and [`FileView::written`] is the file's own text.
    ///
    /// A caller that ignores the difference gets an answer about the wrong place rather than no answer, which is
    /// the worse of the two failures — so the mapping is on the struct rather than a convention.
    pub fn parse_rendering(
        file: &VfsFile,
        rendered: &crate::preprocess::cooked::RenderedCooked,
    ) -> FileView {
        Self::parse_rendering_with_cuda(file, rendered, false)
    }

    /// [`FileView::parse_rendering`] for a **CUDA** unit — the session's configuration decides, and the reason is the
    /// one [`FileView::parse_with_cuda`] gives: the reading an editor asks questions about must agree with the reading
    /// the index was built from.
    pub fn parse_rendering_with_cuda(
        file: &VfsFile,
        rendered: &crate::preprocess::cooked::RenderedCooked,
        cuda: bool,
    ) -> FileView {
        Self::parse_rendering_with_the_files_own_language(file, rendered, cuda, None)
    }

    /// **A rendering parsed as the language the file is**, which is not a detail: the parser's feature set decides
    /// whether `restrict` is a qualifier, whether `0b1011'0110` is a literal, whether `[[fallthrough]]` is an attribute
    /// and whether a statement expression is one. `ParserConfig::default()` is C++17 in this crate, and a rendering
    /// parsed that way answers about a language the file is not — measured on a nine-file C corpus: a `restrict`
    /// parameter reported as a redefinition (a name, not the qualifier), and C23's literals and attributes as syntax
    /// errors.
    ///
    /// The language comes from the file's own [`crate::CompilerConfig`] — its `-std=`, its `.c` extension, what the
    /// project said — which is the same answer [`crate::CompilerConfig::language_for`] gives the lexer.
    pub fn parse_rendering_in(
        file: &VfsFile,
        rendered: &crate::preprocess::cooked::RenderedCooked,
        config: &crate::CompilerConfig,
    ) -> FileView {
        Self::parse_rendering_with_the_files_own_language(
            file,
            rendered,
            config.cuda(),
            Some(config.language_for(&file.path)),
        )
    }

    fn parse_rendering_with_the_files_own_language(
        file: &VfsFile,
        rendered: &crate::preprocess::cooked::RenderedCooked,
        cuda: bool,
        language: Option<cpp_parser::features::LanguageConfig>,
    ) -> FileView {
        let source: Arc<str> = Arc::from(rendered.text.as_str());
        let line_index = Arc::new(LineIndex::parse(&source));
        let mut parser_config = cpp_parser::ParserConfig::default().with_cuda(cuda);
        if let Some(language) = language {
            parser_config = parser_config.with_language(language);
        }
        let tree = cpp_parser::CppParser::parse(&source, parser_config);
        let root = tree.get_red_root();
        // **No macro bodies**, and the answer is the point rather than a simplification: the text being parsed has
        // no invocations in it, so a body reader would be consulted for names that were already replaced.
        let scopes = crate::sema::scopes::build_scopes(&root, &crate::sema::scopes::NoMacroBodies);

        FileView {
            file: file.id,
            path: file.path.clone(),
            source,
            line_index,
            tree,
            root,
            scopes,
            open: file.open,
            written: Some(file.text.clone()),
            written_lines: Some(file.line_index.clone()),
            reading: Arc::from(rendered.spans.as_slice()),
        }
    }

    /// The parse diagnostics, as the parser reported them.
    ///
    /// A tolerant parser reports rather than fails, so this is empty for most files and non-empty for a file being
    /// typed at — which is not the same thing as a file that does not compile.
    pub fn errors(&self) -> &[CppParseError] {
        self.tree.get_errors()
    }

    /// **The ranges to select at `offset`, innermost first** — the chain an editor walks when the user expands a
    /// selection.
    ///
    /// # The ladder
    ///
    /// ```text
    /// the token under the cursor   `size` in `w.size`          a word before anything larger, which is what every
    ///                                                          editor selects first and what a node walk would skip:
    ///                                                          a token is not a node
    /// then each node that contains it, from the innermost out   the member access, the expression, the statement,
    ///                                                          the body, the function, the class, …  the file
    /// ```
    ///
    /// # The two things that make it a *chain* rather than a dump of ranges
    ///
    /// * **Strictly growing**: a recovered tree has nodes whose range equals their parent's (a wrapper around the
    ///   same tokens), and expanding the selection to the same range twice is a keystroke that does nothing. Only a
    ///   range that **strictly contains** the one before it is added.
    /// * **Every range contains the cursor**: an ancestor's range always does, by construction — but a range that
    ///   does not is dropped anyway, because the client is being asked to *select* it, and selecting something else
    ///   than what the user is looking at is worse than not expanding.
    ///
    /// A cursor in whitespace starts the chain at the enclosing node rather than with the whitespace token: there is
    /// no word under the cursor to select, and the next useful thing is what surrounds it.
    ///
    /// # Which text this is asked of is the **caller's** decision, and it is the file's
    ///
    /// The chain is answered in the coordinates of the tree it walks, so this method is the wrong door for a client:
    /// a selection is what the **reader** is about to see highlighted, which makes it a fact about the file's own
    /// text — the same family `folding_ranges` belongs to and `Session::documentation` joined — and
    /// [`Session::selection_chain`](crate::Session::selection_chain) is the query that asks it of the right text.
    ///
    /// Asking a *rendering* cannot be repaired by translating the cursor in and the rungs out, and that is measured
    /// rather than argued: a cursor in whitespace maps **forward** to the next token (which is right for a cursor, and
    /// is what [`FileView::reading_offset_of`] documents), so the walk begins at a token that starts *after* the
    /// cursor, and the first rung does not contain the position it was built for. On the fixture that found this, the
    /// cursor at file offset 9 — the space in `namespace ns` — produced a chain whose innermost rung began at 10.
    pub fn selection_chain(&self, offset: ReadingOffset) -> Vec<cpp_parser::SourceRange> {
        selection_chain_of(&self.root, offset.get())
    }
}

/// **The walk behind [`FileView::selection_chain`]**, over a tree the caller owns.
///
/// Free rather than a method because two callers need it and they hold different trees: a view walks the tree it
/// parsed, and [`Session::selection_chain`](crate::Session::selection_chain) walks a parse of the file's **own** text
/// — which is a tree no `FileView` in this crate holds, because every view is of a rendering. One walk, two trees.
pub(crate) fn selection_chain_of(
    root: &CppSyntaxNode,
    offset: usize,
) -> Vec<cpp_parser::SourceRange> {
    let mut chain: Vec<cpp_parser::SourceRange> = Vec::new();
    let add = |range: cpp_parser::SourceRange, chain: &mut Vec<cpp_parser::SourceRange>| {
        if range.length == 0 {
            return;
        }
        // Inside the cursor, and strictly inside the previous range — see the note on the method.
        if offset < range.start_offset || offset >= range.end_offset() {
            return;
        }
        // Strictly inside the previous range — see the note on the method. A range that merely *equals* the previous
        // one adds nothing: expanding the selection to the same text twice is a keystroke that does nothing.
        let already_covered = chain.last().is_some_and(|previous| {
            range.start_offset >= previous.start_offset
                && range.end_offset() <= previous.end_offset()
        });
        if !already_covered {
            chain.push(range);
        }
    };

    let token = cpp_parser::token_at(root, offset);

    let ancestors = match &token {
        Some(token) => {
            if !cpp_parser::is_trivia(token.kind().into()) {
                add(cpp_parser::source_range(token.text_range()), &mut chain);
            }
            token
                .parent_ancestors()
                .map(|node| cpp_parser::source_range(node.text_range()))
                .collect::<Vec<_>>()
        }
        // No token at that offset (past the end of the file): the node walk still answers, and the root is always a
        // range.
        None => root
            .ancestors()
            .map(|node| cpp_parser::source_range(node.text_range()))
            .collect(),
    };

    for range in ancestors {
        add(range, &mut chain);
    }

    chain
}

impl FileView {
    /// A byte offset from a **line and column**, both counted from zero.
    ///
    /// The mapping a client's positions need, and the one place LSP's own rule is *not* implemented: the columns
    /// this counts are characters, while the protocol counts UTF-16 code units, and the two differ on a line with
    /// an emoji or any character outside the basic plane. That conversion is the protocol layer's — doing it here
    /// would put a rule about a wire format in the crate that has no wire format.
    ///
    /// A lookup in the index the view already holds: no scan, and no way for the answer to be about a different
    /// text than the one parsed.
    pub fn offset_at(&self, line: usize, column: usize) -> Option<ReadingOffset> {
        self.line_index
            .get_offset(line, column, &self.source)
            .map(|at| ReadingOffset::new(usize::from(at)))
    }

    /// A byte offset back to a **line and column**, both counted from zero — the inverse of
    /// [`FileView::offset_at`], and the direction a diagnostic needs: the parser reports offsets and a client wants
    /// a position.
    ///
    /// A position past the end of the text answers `None` rather than clamping: an offset that is not in the file
    /// is a caller's mistake, and a range built from a clamped one would point at the wrong code.
    pub fn position_at(&self, offset: ReadingOffset) -> Option<(usize, usize)> {
        let offset = offset.get();
        self.line_index.position_of(offset, &self.source)
    }

    /// The text, for a caller that wants a `&str` rather than the shared handle.
    pub fn source(&self) -> &str {
        &self.source
    }

    /// **The text of one token**, by the range the token carries — nothing allocated, nothing copied.
    ///
    /// The accessor a **token walk** wants, and the reason it exists: a pass over a file's tokens is the one loop
    /// in this crate that runs once per token — a large header is 60 000 of them — and the two things such a pass
    /// must not do are `token.text().to_string()` (a `String` per token, for a word nobody asked about) and
    /// `&source[start..end]` (a panic when the range is not in this text). This answers `&str` or `None`, and `None`
    /// is a real answer: a pass that walks a rendering's tree against the file's own text gives ranges past the end.
    ///
    /// **Ask the kind first.** A caller deciding "is this token interesting" should decide it from the token's
    /// kind and fetch the text only for the ones that pass — the semantic token layer did the opposite, and paid a
    /// slice per token to colour the keywords among them (`crates/cpp_ls/src/handlers/semantic_token`).
    pub fn get_token_text(&self, range: cpp_parser::SourceRange) -> Option<&str> {
        self.source.get(range.start_offset..range.end_offset())
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::file::paths::MemoryFiles;
    use crate::file::vfs::Vfs;

    /// **The lexical reading, built where a view used to be.** These two tests used `FileView::parse`, which is gone
    /// because a parse of unexpanded text is not a reading of anything. What they were actually about is a position
    /// mapping, and that is [`TokensOf`] — so they moved rather than being deleted, and the property they check is
    /// unchanged: the text a request maps positions in is the text the user is typing, and its line index is the same
    /// generation of that text.
    fn tokens(vfs: &mut Vfs<MemoryFiles>, path: &str) -> (TokensOf, VfsFile) {
        let file = vfs.file(path).expect("the file reads");
        let tokens = TokensOf {
            path: file.path.clone(),
            source: file.text.clone(),
            line_index: file.line_index.clone(),
            open: file.open,
            tokens: cpp_parser::lex(&file.text, &cpp_parser::LexerConfig::default()).0,
        };
        (tokens, file)
    }

    #[test]
    fn a_view_maps_positions_through_the_index_the_vfs_built() {
        let mut vfs =
            Vfs::new(MemoryFiles::new().with_file("/p/a.cpp", "int a;\nint b;\nint c;\n"));
        let (tokens, file) = tokens(&mut vfs, "/p/a.cpp");

        assert!(
            Arc::ptr_eq(&tokens.line_index, &file.line_index),
            "and it shares that file's index rather than making one"
        );
        assert!(Arc::ptr_eq(&tokens.source, &file.text));

        assert_eq!(tokens.offset_at(2, 4), Some(ReadingOffset::new(18)));
        assert_eq!(tokens.position_at(ReadingOffset::new(18)), Some((2, 4)));
        assert_eq!(tokens.offset_at(9, 0), None);

        // **And the tokens really are the file.** The stream covers the text byte for byte, which is what makes a
        // range built from two tokens a range in this file — the property everything lexical rests on.
        let covered: String = tokens
            .tokens
            .iter()
            .map(|t| &tokens.source[t.range.start_offset..t.range.end_offset()])
            .collect();
        assert_eq!(
            covered,
            tokens.source(),
            "the tokens cover the file byte for byte"
        );
    }

    #[test]
    fn a_view_of_an_edited_buffer_maps_positions_in_the_edited_text() {
        // The property a language server depends on: the text a reading maps positions in is the text the user is
        // typing, and its line index is the *same* generation of that text.
        let mut vfs = Vfs::new(MemoryFiles::new().with_file("/p/a.cpp", "int a;\n"));
        let (before, _) = tokens(&mut vfs, "/p/a.cpp");
        assert_eq!(
            before.offset_at(1, 0),
            Some(ReadingOffset::new(7)),
            "a text that ends in a newline has an empty last line, at its end"
        );
        assert_eq!(before.offset_at(2, 0), None, "and no line after that");

        vfs.insert("/p/a.cpp", "int a;\nint b;\n", true);
        let (after, _) = tokens(&mut vfs, "/p/a.cpp");

        assert!(after.open, "and the reading says the text is a buffer");
        assert_eq!(
            after.offset_at(1, 4),
            Some(ReadingOffset::new(11)),
            "`b` of the new second line"
        );
        assert_eq!(
            before.offset_at(1, 4),
            Some(ReadingOffset::new(7)),
            "the older generation's line 1 was the empty line after the final newline, so column 4 clamps to its \
             start — the end of the text"
        );
    }
}