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
//! The on-disk cache: **one file per file**, keyed by a hash of everything that determines a summary.
//!
//! The rules this module implements are the ones fixes; what follows is the part a reader
//! of the code needs to know to change it safely.
//!
//! # Why one file per summary
//!
//! A single blob for the whole project would have to be rewritten whenever any file changes — for a large project
//! that is hundreds of megabytes of I/O per keystroke, and a crash while writing loses everything. One file per
//! summary makes invalidation local, writes independent, and a torn write cost exactly one file.
//!
//! # What the key is made of, and why each part is in it
//!
//! ```text
//! content_hash what the file says — a change here changes the summary
//! context_hash compiler settings and the file's own directory; see below
//! format_version the producer — a parser or schema change makes every summary wrong
//! reading_fingerprint the readers themselves — measured, not remembered; see [`READING_FINGERPRINT`]
//! ```
//!
//! `context_hash` is the configuration **and the directory the file sits in**, which are one question rather than
//! two: `#include "widget.h"` means *the one beside me*, so the same text in two directories describes two
//! different compilations and resolves to two different files. The directory was missing from the key at first, and
//! the hole was invisible until a test put the same text in two directories: the two files shared one entry, and
//! the second one was handed the first one's resolved includes — a jump to a header it does not include.
//!
//! The part of the key that is *not* in it is which file it is: nothing here names a path, only the directory the
//! path is in. That is what makes a branch switch cheap — see [`content_hash`].
//!
//! `format_version` is deliberately the blunt instrument: the grammar is still moving, and a summary written by a
//! different parser is not "probably still fine", it is a **silent** wrong answer. Bumping the number is the one
//! invalidation that must never be forgotten, so it lives in the key rather than in a migration step.
//!
//! It was forgotten, for many rounds — which is why the key also carries a **fingerprint of the readers**
//! ([`READING_FINGERPRINT`]), taken from the versions the build already carries: a rule that depends on remembering is
//! a rule that gets missed, and this one is a constant of the package.
//!
//! # Why the macro environment is *not* in the key
//!
//! A fourth part used to be here: the set of content hashes of the files that define macros on the way in. It was
//! the one part that could not be computed from the text and the path — the file's own `#define`s and its own
//! `#include`s are products of the parse — and that had a consequence the design did not intend: **a lookup could
//! not happen until after the parse**, so the disk cache never saved the thing it exists to save. It saved writes.
//!
//! It is also not needed, and the evidence is a chain of three facts about the producer:
//!
//! * [`crate::build_scopes`] takes only the syntax tree, so declarations are collected from the whole file;
//! * [`crate::build_facts`] takes the preprocessing state to find **where the directives are**, not to decide
//! which branch was taken — every fact records the `#if` it was written in as a [`crate::FactGuard`] and lets
//! the consumer decide, which is the whole reason guards are stored rather than applied;
//! * `#include MACRO` — the one directive whose meaning depends on expansion — is **never** resolved
//! (`crate::include`'s resolver returns `Unresolved` for it, and says so), so a file that writes one is not
//! stored at all.
//!
//! So a summary is a function of the text, the directory, the configuration and which candidate headers exist —
//! not of which macros were in force. **If that ever stops being true** — macro expansion inside declarations, or
//! pruning the untaken branch of an `#if` — the environment has to come back here *and* [`FORMAT_VERSION`] has to
//! be bumped in the same change, because summaries already on disk would be silently stale rather than merely
//! unreachable.
//!
//! # Why the hash is written here rather than taken from `std`
//!
//! `DefaultHasher` is explicitly allowed to change between Rust releases, and a cache key that changes when the
//! compiler is upgraded is a cache that silently misses forever (or worse, hits with a different meaning if the
//! value is ever persisted). FNV-1a is fixed by definition, is a few lines, and is strong enough for this job: the
//! key guards a **local** cache, and a collision costs a stale summary for one file — a wrong answer a re-parse
//! fixes, not a security boundary.
// **What the cache stores, and what it reads back.** A summary is the unit the whole cache is built from, the two
// codecs are its bytes, and memory/alloc are the two numbers a report about it needs. align is here because
// the thing it compares against a compiler is a RenderedUnit --- the cached reading of a program.
/// **The environment as a value** — see `docs/module-cache.md`.
/// **Where a read's allocations go**, when the perf-probe feature is on --- a stage's own marks, next to the
/// counter that reads them.
use ;
/// The version of everything that produces a summary: the parser's grammar, this crate's summary schema, and the
/// meaning of the fields in it.
///
/// **Bump on any change that could make an old summary wrong.** See the module documentation for why this is part
/// of the key rather than handled by a migration.
///
/// A parser change reaches the key through [`READING_FINGERPRINT`], which carries `cpp_parser`'s version. A change to
/// *this* crate''s own readings leaves no such trace, so it is this number that is bumped — the same lever a
/// dependency bump uses. The number is still the blunt instrument: every entry becomes unreachable.
///
/// # Why this moved to 4
///
/// **A `_BitInt(`-first class-body member was lost from the summary.** `struct bits { _BitInt(13) signed_wide : 13; }`
/// produced no declaration at all: the specifier loop read `_BitInt(13)` as an unexpanded macro and `signed_wide` as
/// its *type*, so the member had no declarator. Every cache written before that fix holds a summary missing those
/// members, and the member list is built from the summary — the stale answer is visibly wrong, not merely old.
///
/// # Why this moved for version 14 of the codec
///
/// A fact's `type_of` is read from the syntax now rather than assembled out of a declaration's text, and the two
/// readers disagree about **what a type is called**: the old one answered `const [[nodiscard]] constexpr size_type`
/// and `Point>` where the new one answers `size_type` and `std::vector<Point>`. The bytes are the same shape, so an
/// old entry still decodes — which is exactly why this number has to move rather than the codec's: an entry that
/// decodes but says something this build would not write is the case this constant exists for.
///
/// # Why this moved to 11
///
/// **A refined reading is stored now, under the closure it was read in.** The second pass used to throw its answer away
/// at the end of every run because the key could not name the environment, and that is why *every* start re-read the
/// whole project (~120 s on `EmmyLuaCodeStyle`). `SummaryKey::env_hash` is that environment now — the closure
/// fingerprint — and the database honours it instead of hardcoding `env: 0`.
///
/// The count of readings per file changed with it: one file now has the unrefined reading (`env: 0`) and the refined
/// ones, so collection had to stop keeping a single environment per file. That is a change of what an entry means, which
/// is what this constant invalidates.
///
/// # Why this moved to 10
///
/// **A declaration records the reflection annotation it was written under.** `UCLASS(Blueprintable)` and
/// `UPROPERTY(EditAnywhere, Category="Game")` are empty macros, so a summary that does not record them describes a
/// declaration whose meaning to Unreal's build tool is lost — and the specifiers are what `ue-specifier` and a hover
/// read. The layout moved with the field, but the reason this number moves too is the usual one: an old entry decodes
/// and answers "unannotated" for declarations that are annotated.
///
/// # Why this moved to 9
///
/// **An include guard's body is empty, and a cached entry has to say so.** `#define CORPUS_H` used to record the trivia
/// after the name as its body — for a guard followed by a comment block, the comment itself (355 bytes in
/// `c-project/include/corpus.h`), so `macro-parentheses` read a `:` out of prose and told the reader to write
/// `#define CORPUS_H(…) (…)`. The bytes are unchanged (`body_range`, a new answer), so an old entry decodes happily and
/// keeps the false warning — the case this constant exists for. [`crate::cache::FORMAT_VERSION`] moves with
/// `CODEC_VERSION` because a summary and its codec cannot disagree about what a range means.
///
/// # Why this moved to 8
///
/// **A function's facts record which parameters it frees.** `void release(T* p) { delete p; }` now carries a bit for
/// parameter 0, which is what lets `use-after-free` report `release(p); p->x;` when `release` is declared in a header.
/// The field is new, so the *layout* moved too — but the reason this number moves as well is the one that always
/// applies: an entry written before this describes a function without saying what it does to its arguments, and that
/// is a wrong answer rather than an old one.
///
/// # Why this moved to 7
///
/// **A namespace alias records the namespace it names.** `namespace views = ranges::views;` gave the fact an empty
/// `type_of`, so a query for the names written in `std::views` answered nothing — while every adapter a reader types
/// there (`filter`, `transform`, `reverse`, `drop`, `take`) is declared in `std::ranges::views`. The summary's *layout*
/// is unchanged (the target is the existing `type_of` field), so an old entry decodes happily and keeps the empty
/// answer — which is exactly the case this constant exists for.
///
/// # Why this moved to 5
///
/// **A declaration whose name spells its type's last segment recorded `void`.** `std::any any = 1;` — and `Widget
/// Widget;` or `S S;` in any file — was read as an *out-of-line definition* of `any`, because the specifier `std::any`
/// ends with `::` and the declared name. The type was thrown away, the fact said `void`, and `assign-type-check` then
/// reported the initialisation as a conversion "from `int` to `void`". The bytes are unchanged, so an old entry decodes
/// happily and keeps the wrong type — the case this constant is for.
///
/// # Why this moved to 16
///
/// **An `#include`'s range is the directive's own line**, where it used to be the tree's span: that one runs through
/// the trailing trivia to the next real token, so `include-not-found` underlined the comment *under* the directive as
/// well (reported from an editor with a screenshot). The bytes are unchanged, so an old entry decodes happily and
/// keeps the wide range — and the diagnostic stays two lines tall until the file is re-read.
///
/// # Why this moved to 15
///
/// **`T x(a, b);` is read as an initialisation when `a` is a value** (the most vexing parse, resolved by lookup), and a
/// variable never records a function type. A summary written before it says `lock` is a function — or a variable of type
/// `std::unique_lock<std::mutex>(mutex, std::defer_lock)` — for text that now answers a variable of
/// `std::unique_lock<std::mutex>`.
///
/// # Why this moved to 14
///
/// **The grammar reads a directive where an operand goes** (`a || #if … b #endif`), and a summary written by the older
/// grammar is wrong for the same text rather than missing: on `bits/shared_ptr_base.h` it filed everything after
/// `_M_get_deleter` inside `_Sp_counted_ptr_inplace`, which cost `__shared_ptr` its base clause. Measured: the stale
/// `C:\Users\zc\Desktop\test_cpp\.cppls` answered `std::_Sp_counted_ptr_inplace` for `_Sp_overwrite_tag` until it
/// was deleted, and `std` after — a grammar fix that does not move this number is a fix nobody sees.
///
/// # Why this moved to 13
///
/// **The type a deduced `return` states is now composed from typed nodes rather than cut out of the declaration's text**,
/// and the two disagree where the cut was wrong: `int* q` was `int` before the pointer moved into the spelling, so every
/// `auto f(int* q) { return q; }` recorded a fact that offered `int`'s members instead of the pointee's. The key's parts are
/// unchanged, so an entry from before this bump decodes happily and keeps the answer — measured: the stale `C:\p\.cppls`
/// of the `/p` fixtures made `a_function_with_no_written_return_type_states_one_in_its_body` fail for a fix that was in the
/// binary, and pass on a cold cache.
/// # Why this moved to 18
///
/// **A class definition whose head writes a qualified name is a declaration again.** `qualified_specifier_name_node`
/// took `A<T>::From` — a dependent type *inside the argument list* of `struct B<A<T>, void_t<typename A<T>::From>>`
/// — for the declaration's own name, so the whole partial specialization was read as an out-of-line definition of a
/// class the file has not built: no binding, no class scope, no members, and **no fact**. That is what kept
/// `_Is_default_allocator<allocator<_Ty>, …>` out of MSVC's `<xmemory>`, and with it the trait that decides
/// `allocator_traits`'s `conditional_t` base. An entry from before this bump decodes happily and holds the missing
/// fact, so every existing cache has to be dropped — measured on `EmmyLuaCodeStyle`, where `auto pos = events.size();`
/// still answered `_Alty_traits::size_type` from a summary built by the old reader.
///
/// # Why this moved to 19
///
/// **A C file is read with C's keyword table**, so `new`, `delete`, `this`, `operator`, `template` and the alternative
/// spellings (`compl`, `not`, `and`, …) are ordinary identifiers in `.c` and `.i` files instead of C++ keywords. A
/// summary written before this holds one expression statement where a function with a parameter named `delete` was,
/// and no declaration for a variable named `new` — measured on neovim: 28 files of 517 had a parse error before the
/// gate and 17 after, and 13 lines stopped being unparsable. The key's parts are unchanged, so the old entries decode
/// happily and keep the missing declarations, which is what this number is for.
/// # Why this moved to 20
///
/// **A parenthesised declarator is a declarator**, so `static char *(names[3]) = { … };` declares `names` and no
/// longer an unnamed function with a parameter, and `int (catf) (int)` names the parameter it holds. A summary
/// written before this holds no fact for the table (`neovim`'s `src/nvim/option.c:210` and seven more), or holds the
/// parenthesised name as a *parameter* of a function that names nothing. The key's parts are unchanged, so the old
/// entries decode happily and keep the wrong facts — which is what this number is for.
/// # Why this moved to 21
///
/// **A parenthesised declarator with an initializer is a declaration even when its type is a name this file's own
/// reading has never seen.** `static histentry_T *(history[HIST_COUNT]) = …` is neovim's `cmdhist.c:35`, where
/// `histentry_T` is a typedef from `cmdhist.h`; the `=` is what decides, because the left of an assignment must be
/// a modifiable lvalue and a product is not one. Before this the table had no fact at all, or a parameter invented
/// from the group — the same shape the entry for 20 describes, one spelling further out. The key's parts are
/// unchanged, so an old entry decodes happily and keeps the missing declaration.
/// # Why this moved to 22
///
/// **A header's own include guard no longer empties its rendering.** The composed environment — what a header gets
/// when no program read it — took the file's *own* unconditional macro facts, and the summary records
/// `#ifndef X / #define X` as unconditional on purpose (`deguard_the_files_own_guard`). So `X` was defined before the
/// first line, `#ifndef X` was false, and every guarded header rendered to nothing: neovim's
/// `.deps/usr/include/uv.h` was 13 263 tokens in and **0 bytes** out, and its cooked reading was filed with 0
/// declarations where the file has 1 912. Those empty readings are on disk, so the number moves.
/// # Why this moved to 23
///
/// **An enumeration's name is read where the language writes it, between the keyword and the body.** The name
/// was the first `NameExpr` in the subtree, which for an anonymous enum is the first identifier of an
/// enumerator's *initializer*: `enum { A = 1, B = A };` named the enum `A`, filed every enumerator in scope `A`,
/// and recorded a bogus *type* fact at the initializer's use. Measured on neovim's `src/nvim/state_defs.h`:
/// `MODE_INSERT` came out `variable in REPLACE_FLAG` (the identifier `MODE_REPLACE`'s initializer names), and
/// the number moves.
/// # Why this moved to 24
///
/// **A declaration fact records whether it is an enumerator.** `DeclKind` has one variant for "a name that
/// holds a value", and the index inferred the distinction from the absence of a written type plus the presence
/// of a scope — so an **anonymous** `enum { WILD_FREE, … }`'s members, which have no scope, were drawn as
/// variables in every file that used them (measured on neovim's `cmdexpand.h`: the declaration card said "an
/// enumerator", the use in `cmdexpand.c` said "a variable"), and an untyped scoped variable was drawn as an
/// enumerator. The fact carries the flag now; entries written before it decode with `false`, so the number moves.
/// # Why this moved to 25
///
/// **A header resolves its includes with the flags of the source beside it.** A build lists its sources, so
/// `command_for(header)` was `None` and the project-wide configuration answered — without the `-I`/`-isystem`
/// directories the build passed — measured on neovim, where eleven headers of one closure could not resolve
/// `<uv.h>` although `src/nvim/os/fs.c` beside them resolves it from its response file. Those headers' summaries
/// carry the unresolved includes (`IncludeFact::resolved`), and one unresolved include is what takes the macro
/// environment's completeness claim back for every file that reaches it, so the number moves.
/// # Why this moved to 26
///
/// **Which translation unit a header is cooked in comes from the index, not from what is held.** A header's
/// environment used to be "the smallest root among the units that happen to be in memory", so the same header
/// could be rendered two ways in one session and two runs of one binary disagreed (the census measured `grid.h`
/// at 2 parse errors in the 517-file session and 0 alone). The unit is now the root the include graph names, and a
/// unit it does not name never answers — when the named one is not held the environment is composed from the
/// index. Cooked readings already on disk were made under the old choice, so the number moves.
/// # Why this moved to 27
///
/// **`std::println("…", 1);` is a call, and it was parsed as a declaration.** A qualified declarator is legal C++
/// (`void A::f() {}`), so the speculative declaration pass accepted the statement with no error — and a
/// declaration fact for `println` in scope `std` was filed from it, while the statement itself had no `CallExpr`
/// for a hover to resolve the overload with. Measured on `test_module`: four `std::println` declarations listed,
/// with the card saying the arguments would decide. Summaries on disk hold the bogus fact, so the number moves.
/// # Why this moved to 28
///
/// **C++26 static reflection parses.** `^^T`, `[: r :]`, `typename [: r :]`, `d.[: r :]` and `typename [: r :]<…>`
/// were syntax errors before this — a file that uses them had no tree at all past the first `^^`, so the facts a
/// summary holds for such a file (and for every declaration after the first error) are not the ones the reader gets
/// now. Nothing about a *non*-reflection file changes, and the number moves anyway because a summary is keyed by
/// content: a file edited to use reflection would otherwise keep a summary read before it did.
/// # Why this moved to 29
///
/// **C++26 contracts parse.** `pre(…)`/`post(…)` after a parameter list and `contract_assert(…)` in a body were
/// syntax errors before this — a `pre(…)` was read as a macro invocation *inside the declarator*, so the function it
/// decorated was filed with the wrong shape (and a `contract_assert` ended the statement it was in). A summary for
/// such a file holds facts read from a tree that ended at the first contract, so the number moves.
/// # Why this moved to 30
///
/// **Two modifier bits a fact did not have**: `DEFINED` (the declaration carries a body, or is `= default`/`= delete`)
/// and `PURE` (`= 0`). They are written by the same walk that computes the other bits, so a summary on disk from
/// before them says "not defined" about every function — which is the answer a "create the definition" edit acts on.
/// # Why this moved to 31
///
/// **Two C++26 forms parse that did not**: `typename [: r :]` in *expression* position (a temporary or a functional
/// cast of a reflected type) and `template for (…)` — the expansion statement, which used to leave its `template`
/// token flat in the enclosing block while the loop was read as an ordinary one, with **no error to show for it**.
/// A cached reading holds that tree, and the cached parse errors with it: measured on `C:\Users\zc\Desktop\cpp`,
/// `reflect.hpp` reported two `expected a type specifier` errors *after* the parser had learned the statement, because
/// the reading was the one the old parser produced. The number moves so the tree is read again.
/// # Why this moved to 32
///
/// **`__cplusplus` and one new macro decide which half of a header exists.** `c++23` was answered `202311L` (a draft
/// number; the compiler says `202302L`) and `c++26` was answered *nothing*, and `-freflection` now defines
/// `__cpp_impl_reflection` — the macro libstdc++`s `<meta>` is gated on. Every `#if __cplusplus > 202302L` in every
/// header therefore had an answer it did not have before, and the conditions are exactly what a cached summary
/// records: measured on `C:\Users\zc\Desktop\cpp`, `std::meta` had **no fact at all** until this changed, so hover and
/// go-to-definition answered nothing in a file that compiles.
/// # Why this moved to 33
///
/// **`consteval string_view f(info);` is a function, not a variable** — the "most vexing parse" is settled by lookup
/// and this parser now asks the question the language asks. Every such declaration in libstdc++`s `<meta>` changed
/// kind, and a fact`s *kind* is what hover, completion and the call checks read: a cached summary that still holds
/// `identifier_of` as a variable answers with the type of the call instead of the declaration.
/// # Why this moved to 34
///
/// **A known type name followed by a name now ends the specifier sequence.** `EXTERN colnr_T dollar_vcol INIT( = -1);`
/// used to be read as the type `EXTERN colnr_T dollar_vcol` and the declarator `INIT`, so the variable the line
/// declares — and every declaration after it in the header — was lost. A summary or a cooked reading made before this
/// holds the loss: neovim's `globals.h` alone is sixteen declarations, and 135 `undefined-name` findings followed.
/// # Why this moved to 35
///
/// **A qualified call is not a declaration.** `std::ranges::find_if(items, f);` was read as a `Declaration` whose
/// declarator was the call, so a summary recorded a function called `find_if` in `std::ranges` — a fact that does not
/// exist — and no `CallExpr` for the statement itself (`a56783f2`). A summary made before this holds the phantom
/// declaration, and every algorithm called at statement scope was invisible to hover, signature help and the checks
/// that read a call.
///
/// # Why this moved to 37
///
/// **A declaration's recorded type keeps its `const`.** `read_specifiers_named` dropped qualifiers on the argument
/// that they say nothing about *which class* a spelling names — true for a member lookup, false for the type a
/// declaration records:
///
/// ```text
/// static constexpr const char* FacilityName = "RelayServer"; recorded char*, written const char*
/// ```
///
/// The value is a string literal, whose type is `const char*`, so `assign-type-check` reported that it "does not
/// convert to `char*`" on a line a compiler accepts — and the hover on that declaration showed the truncated type.
/// Every summary made before this holds the truncated `type_of`, and `type_of` is what both read.
///
/// # Why this moved to 36
///
/// **The macro environment a closure composes is part of the reading.** `the_indexed_environment` took each
/// included file's **last definition** of a name and never let an `#undef` decide one, and it walked the closure
/// breadth-first backwards — so a precompiled header that includes the SDK's `min`/`max` and then `#undef`s them
/// left both names defined, and `std::min(a, b)` was cooked into `std::((( a ) < ( b )) ? ( a ) : ( b ))`. A
/// rendering made before this holds the expansion, and it is keyed by the environment it was made from — which was
/// itself the wrong one, so no other change reaches it. See `tests/undef_of_an_included_macro.rs`.
/// # Why this moved to 38
///
/// **A composed environment is a timeline, and it evaluates the conditionals it stored.** Two changes, both of which
/// change what a rendering says:
///
/// * a `#define` inside an `#if` is decided from the stored question instead of being ignored, so a header whose
/// macros live behind a guard (`JSON_TRY`, `JSON_CATCH` in `nlohmann/detail/macro_scope.hpp`) now expands instead
/// of being left as text;
/// * the environment carries each included file's contribution **at the offset of the `#include` that reached it**,
/// and an `#undef` is a decision like a definition — so `json.hpp`'s `detail/macro_unscope.hpp` no longer takes
/// `JSON_TRY` away from the whole file, only from the point it is included at.
///
/// Measured on `nlohmann/json.hpp`: the cooked reading went from 6 parse errors and **151** `ClassBody` children to
/// **0** errors and 242 members of `basic_json`, `operator[]` among them — the members after the first `at` had been
/// filed without their class scope, which is what made `json["data"].` unanswerable.
///
/// # Why this moved to 39
///
/// **A seed is part of the reading, and the seed now depends on the file's language.** The toolchain's predefines are
/// probed once, with a `predefined.cpp`, so every `.c` file was cooked with `__cplusplus` and `_MSVC_LANG` in force:
/// MSVC's `string.h` then contributed its `extern "C++" { template … }` overloads to a C program's stream, and the
/// parse of that stream reported `expected primary expression` inside text no C compiler reads. A stored rendering
/// made that way is keyed by a closure and an environment that did not change, so nothing but a version reaches it —
/// measured on Lua 5.5.0's `ldebug.c` with a cache from before the fix: **30** syntax errors still published, against
/// 0 with the same binary and an empty cache.
///
/// # Why this moved to 40
///
/// **A program stream's spelling is part of the reading.** `RenderedUnit`'s writer spaced every token of a macro
/// expansion apart (it compared *written* ranges, and one expansion's tokens all carry the invocation), so `>=` came
/// out as `> =` and the program read of a C file reported `expected primary expression` — 15 of them on Lua 5.5.0's
/// `ldebug.c`. A stored program reading made that way is keyed by the closure it was read from, which did not change,
/// so only the version reaches it.
///
/// # Why this moved to 41
///
/// **A fact's kind is part of what a summary says, and the scope walker changed it.** `struct CallInfo *previous;`
/// was filed as a *type*: the class-like keyword was read as introducing the declarator's name. Every field declared
/// with an elaborated-type-specifier had the wrong kind, and the semantic tokens coloured it as a type — reported from
/// an editor on Lua 5.5.0's `ldebug.c` (`ci->previous`). Measured: `inspect facts` on `lstate.h` answered
/// `190:20 previous type in CallInfo`, and `CallInfo`'s member list held a member named after the tag. A stored
/// summary filed the old kind, and only the version reaches it.
///
/// # Why this moved to 42
///
/// **A parameter list is part of what a summary says, and the declarator's reader changed it.** `LUA_API void
/// (lua_setfield) (lua_State *L, int idx, const char *k);` — a parenthesised declarator, which is how Lua writes its
/// whole public API — parsed with its `ParameterList` *beside* the declarator rather than inside it, so
/// `CppDeclarator::get_param_list` found nothing: the fact was a function with no `parameters`, the hover card printed
/// `lua_setfield(…)`, no inlay hint was placed, and its parameters were filed as **file-scope variables**.
/// `inspect facts` on `lua.h` answered `281:16 lua_setfield function returns `void`` with no list. A stored summary
/// carries the empty list, and `cpp_parser::VERSION` is the package version — it does not move for a reader's change —
/// so only the version reaches it.
/// # Why this moved to 43
///
/// **A type's spelling is part of what a summary says, and the declarator's shape changed it.** `2b07593a` made a
/// declarator keep its own suffixes, so the readers that write a type back changed what they answer for the classic C
/// declarators: `int (*table[3])(int);` was `int ([3]*)(int)` (the operators in the wrong order around the name) and is
/// `int (*[3])(int)` now, and a function returning a function pointer records `int (*)(int b)` rather than `int`. A
/// stored summary carries the old spelling, and only the version reaches it.
/// # Why this moved to 44
///
/// **A type's spelling drops a parameter list's names, and the readers now do.** `typedef int (*binary_op)(int left,
/// int right);` names the type `int (*)(int, int)`: the names are not part of it, and a stored summary that kept them
/// (`int (*)(int left, int right)`) answered a different spelling from the one a consumer comparing types expects.
pub const FORMAT_VERSION: u32 = 44;
/// **The fingerprint of the readers a summary was built by**, in the key.
///
/// # Why this is not [`FORMAT_VERSION`]
///
/// A manual number is only as good as the memory of whoever changed the code, and this one was forgotten for many
/// rounds: the grammar moved while `FORMAT_VERSION` stayed at 1, and every entry on disk quietly described an older
/// reader. So the key also carries a number that is computed rather than remembered.
///
/// # Why it is computed from versions, and not from a hash of the sources
///
/// A `build.rs` used to hash this crate's `src` and `cpp_parser/src` and pass the result in as
/// `CPP_READING_FINGERPRINT`. That was the right idea and it could not be **published**: `cargo publish` builds the
/// crate from the `.crate` archive, where `../cpp_parser/src` does not exist, so the verification build panicked
/// before the crate could be uploaded.
///
/// What replaces it is computed from what the archive does contain:
///
/// * `cpp_parser::VERSION` — the parser's sources move with its version, and a released binary is the only one
/// whose cache survives a restart into a different parser;
/// * this crate's own `CARGO_PKG_VERSION` and [`FORMAT_VERSION`] — the numbers that move when a *reading* of this
/// crate changes;
/// * [`crate::summary_codec::CODEC_VERSION`] — the number that moves when the **record** changes shape. It belongs
/// here rather than being left to the record's own header because not everything keyed by this fingerprint is a
/// summary: a unit's rendering, its facts and a walk contribution are all derived from summaries, and a decoder
/// that drops a field makes every one of them wrong. Measured, for version 39 of that number: `visit_once` was
/// never written, so a warm start made the walk re-enter every `#pragma once` header at every inclusion — one
/// header appeared **18 times** in a program's stream and a class answered 108 members with 18 same-named ones —
/// while a cold start, whose summaries were never decoded, answered one. A codec bump that leaves a rendering
/// keyed as before serves that wrong stream for as long as the files it names do not change.
///
/// # The cost, written down rather than hidden
///
/// A grammar edit **between two versions** — a local build, a debug session — is a cache that still answers for the
/// old grammar, and `FORMAT_VERSION` is the lever for that during development, exactly as it is for a dependency
/// bump that changes a reading. A build that wants a different number can raise `FORMAT_VERSION`; nothing is
/// forgotten silently, and no file outside the package is read.
///
/// # It is still computable before the file is parsed
///
/// A constant of the binary, so a lookup can happen before the parse — which is the property the key must keep, and
/// the reason the macro environment could not stay in it.
pub const READING_FINGERPRINT: u64 = ;
/// FNV-1a's 64-bit offset basis and prime — fixed by definition, so the number does not move when a compiler is
/// upgraded.
const FNV_OFFSET_BASIS: u64 = 0xcbf2_9ce4_8422_2325;
const FNV_PRIME: u64 = 0x0000_0100_0000_01b3;
/// **FNV-1a, as a `const fn`** — the fingerprint has to be a constant: it is written into the key of every cache
/// file name, and a runtime hash is a runtime failure waiting for a code path with no way to report one.
const
/// How much the summary cache may hold before a sweep starts removing the oldest entries.
///
/// A budget rather than "never delete", because nothing else bounds the directory: every distinct text a file ever
/// had, in every compilation, is an entry of its own — that is what makes a branch switch cheap — and a cache that
/// only grows is a `.cppls` that one day is the largest thing in the checkout.
pub const CACHE_BUDGET_BYTES: u64 = 2 * 1024 * 1024 * 1024;
// Sweep `<cache>/summaries`: remove what can never be served, then the oldest until the rest fits `budget_bytes`.
//
// # Why this is needed, and why it is safe to run beside a session
//
// The key contains [`READING_FINGERPRINT`], which is a hash of the readers' source, so **every change to a reader
// makes every entry written before it unreachable** — not wrong, just never asked for again. Nothing removed them.
// A developer of this crate, or a user upgrading it, left a whole project's worth of summaries behind each time.
//
// A sweep only ever removes files a cache miss would rebuild: an unreachable file is never looked up, and a file
// removed for being old is one the next run re-derives. A file that disappears between the directory listing and
// the removal is somebody else's sweep, and is not an error. Writes are `.tmp` then rename
// ([`crate::index::write_summary`]), so a sweep never sees half a summary; a `.tmp` it finds is removed only when
// it is old enough that no writer can still own it.
//
// A missing cache directory is an empty cache, and the sweep does not create it.
//
// "Oldest" is by modification time — a hit does not rewrite an entry, so this is *first written*, not *last used*,
/// The directory name this crate keeps its cache in, under the project root.
///
/// **Defined in `cpp_toolchain`, and re-exported here.** Two layers name the directory — the toolchain's project
/// scan must never descend into it, and this crate writes summaries there — and a name with two definitions is a
/// cache that is written into one directory and read from another.
pub use CACHE_DIRECTORY;
/// Everything that determines what a summary of one file contains.
///
/// Built by the caller, which is the only place that knows the compiler configuration and the directory the file
/// is compiled in; this type's job is to turn them into one stable key.
///
/// There is no macro-environment part, and the module documentation gives the evidence for why. The practical
/// consequence is the one that matters: **every part of this key is computable from the text and the path**, so a
/// lookup can happen before the file has been parsed.
// **The two hashes every key is built from, defined in `cpp_toolchain` and re-exported here.** The same function
// hashes a file's content, the configuration and the macro environment — three places that must agree, and the only
// way to make them agree is one implementation. The toolchain needs it first: its own cache is filed under a hash of
// the compiler's output.
pub use ;
// The hash of a file's text, as the cache sees it, is [`cpp_toolchain::content_hash`].
//
// Nothing about *where* the file is enters it, which is what makes a branch switch cheap: a file that comes back to
// a content the cache has seen — after `git checkout`, a revert, or a rename within its directory — is found without
// being parsed. The directory is a separate part of the key, because the text alone does not determine what its
// includes resolve to.
/// **The key a translation unit's rendering is filed under** — the files the walk read, their texts, and the reader
/// that would produce the stream.
///
/// The *inputs* say which program this is: a file the reader has open and has not saved comes from the overlay, so an
/// edit changes the program without changing its name, and a key over the names alone would answer with text the files
/// no longer have. The **fingerprint** says which reader read it, and it is here for the reason
/// [`SummaryKey::reading_fingerprint`] states for summaries: a rendering is a function of the cook and of the parse as
/// well as of the bytes, and a key that names only the bytes keeps serving a stream an older build produced.
///
/// # The measurement
///
/// It was missing, and a real project's hover carried it. The rendering that answered for `CodeFormatCLib.cpp` was
/// 919 228 tokens with `struct FormatRange` **18 times** in it — the class's member list answered 108 members with
/// **18 named `EndLine`**, and the popup drew thirteen-odd identical lines `std::size_t EndLine` — where the same
/// project rendered 742 907 tokens and **one** copy once its broken summary was re-read. An entry like that had no
/// key component that could move when the reading moved: every reader that produced it folded the closure's texts and
/// nothing else, so the text being unchanged made the answer permanent. (The reading itself was the defect —
/// `visit_once` lost in the summary's codec, [`crate::summary_codec::CODEC_VERSION`] 39 — but a cache that cannot tell
/// two readers apart is how a fixed reading keeps answering.)
///
/// Sorted here rather than by the callers, because two callers compute this key — the render, and the check that a
/// stored rendering still describes the files it names — and a disagreement about the order would be a permanent cache
/// miss for one of them.
/// [`a_rendering_key`] with the fingerprint as a parameter — the only way to test that the key folds it, since the
/// real one is a constant.