cpp_code_analysis 0.4.0

The analysis layer of cpp_ls: the preprocessor, symbol scopes, type inference and the semantic checks.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
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
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339
2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
2382
2383
2384
2385
2386
2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410
2411
2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
2427
2428
2429
2430
2431
2432
2433
2434
2435
2436
2437
2438
2439
2440
2441
2442
2443
2444
2445
2446
2447
2448
2449
2450
2451
2452
2453
2454
2455
2456
2457
2458
2459
2460
2461
2462
2463
2464
2465
2466
2467
2468
2469
2470
2471
2472
2473
2474
2475
2476
2477
2478
2479
2480
2481
2482
2483
2484
2485
2486
2487
2488
2489
2490
2491
2492
2493
2494
2495
2496
2497
2498
2499
2500
2501
2502
2503
2504
2505
2506
2507
2508
2509
2510
2511
2512
2513
2514
2515
2516
2517
2518
2519
2520
2521
2522
2523
2524
2525
2526
2527
2528
2529
2530
2531
2532
2533
2534
2535
2536
2537
2538
2539
2540
2541
2542
2543
2544
2545
2546
2547
2548
2549
2550
2551
2552
2553
2554
2555
2556
2557
2558
2559
2560
2561
2562
2563
2564
2565
2566
2567
2568
2569
2570
2571
2572
2573
2574
2575
2576
2577
2578
2579
2580
2581
2582
2583
2584
2585
2586
2587
2588
2589
2590
2591
2592
2593
2594
2595
2596
2597
2598
2599
2600
2601
2602
2603
2604
2605
2606
2607
2608
2609
2610
2611
2612
2613
2614
2615
2616
2617
2618
2619
2620
2621
2622
2623
2624
2625
2626
2627
2628
2629
2630
2631
2632
2633
2634
2635
2636
2637
2638
2639
2640
2641
2642
2643
2644
2645
2646
2647
2648
2649
2650
//! Building one file's [`FileSummary`] — the join nothing else in this crate performs.
//!
//! # Why this needs a module of its own
//!
//! The three passes a summary is made of are each somebody else's job and none of them knows about the others:
//!
//! ```text
//! cpp_parser                 the tree
//! preprocess::preprocess     the directives, the macro table, the conditions
//! sema::build_scopes         the scopes and their bindings
//! declarations::build_facts  the declarations *and* which `#if` each was written in   ← needs all three
//! ```
//!
//! [`crate::build_facts`] needs the scopes *and* the preprocessing, because a declaration has to say which
//! conditional region it is in — and neither of those layers can produce it alone. That join is what this module
//! is, and writing it anywhere else would mean one of the three layers reaching into another.
//!
//! # What is deliberately not here
//!
//! No caching, no filesystem walks, no invalidation. This builds a summary from text it is given; deciding
//! *whether* to build one, and what to do with the result, is [`crate::cache`]'s and the consumer's business.
//! Keeping the decision out is what makes this testable on a string with no project around it.
//!
//! # Why the resolver is optional
//!
//! An include's target is a fact about the file, but *where it resolved to* is a fact about the project and its
//! include paths. A caller with no configuration — a test, or an editor looking at a file outside any project —
//! still gets every other fact, and the includes come out unresolved with their spelling intact. That is the
//! honest answer rather than a missing one: the file said `#include "widget.h"` and nothing here knows where
//! that is.

// Until the splice is in, the type and its fields are read by nothing but their own tests, and an
// allow here is the honest way to say so rather than a green build bought by deleting the tests.
#[allow(dead_code)]
pub mod walk_cache;
pub mod walk_cache_codec;

use std::path::{Path, PathBuf};

use cpp_parser::{CppParser, CppSyntaxTree, ParserConfig};

pub mod effect;
pub mod environment;
mod names;
pub mod project;
pub mod references;
pub mod store;
pub mod surface;
pub mod walk_census;
pub mod watch;
pub mod worklist;

pub use environment::{MacrosHere, visibility_at};

pub use project::{
    CookedFile, HeaderTarget, IncludeVisibility, MemberCompletions, MemberList, NameCompletions,
    NameProvenance, OfferedName, ProjectDefinition, ProjectDefinitions, ProjectIndex, ProjectMacro,
    ProjectMember, ProjectSymbol, UnlistedBase, VisibleDeclaration, definition_across_files,
    definitions_across_files, header_at, macro_across_files, member_across_files,
    member_completions_at, member_definitions_across_files, members_of, name_completions_at,
};
pub use references::{
    FileReferences, MacroReferences, Reference, ReferenceBudget, ReferenceKind, Rename,
    SymbolReferences, SymbolToFind, macro_references, symbol_references,
};
pub use store::{
    IncludeBudget, IncludeIndex, NotIndexed, NotIndexedReason, StoreStats, SummaryStore,
    UnresolvedEdge,
};
pub use watch::{ChangeBatch, EventKind, FileEvent, PathPattern, Response, WatchFilter};
pub use worklist::{Priority, Step, StepOutcome, Worklist, outcome_of};

use crate::cache::{SummaryKey, content_hash};
use crate::file::paths::{FileProvider, PathInterner};
use crate::include::IncludeResolver;
use crate::include::config::CompilerConfig;
use crate::preprocess::directive::{Directive, SpannedDirective};
use crate::sema::declarations::{assign_guards, build_facts, mark_settling_macro_facts};
use crate::sema::scopes::build_scopes_with;
use crate::summary::{FactGuard, FileSummary, IncludeFact, MacroFact};
use crate::summary_codec::DecodeError;

/// Everything needed to turn a file's text into a summary, minus the text.
///
/// The resolver is a [`FileProvider`] and a [`CompilerConfig`] rather than an [`IncludeResolver`] because the
/// resolver borrows both, and a caller indexing a project wants to keep the configuration and the provider around
/// across calls.
pub struct FileIndexer<'a, F: FileProvider> {
    files: &'a F,
    config: &'a CompilerConfig,
    /// What the file's **includes** say about the macros it invokes — see [`crate::sema::scopes::MacroBodies`].
    ///
    /// Optional because most callers have no include closure: a buffer on its own, a test, a probe over a list of
    /// files. `None` is "nobody says", which produces exactly the summary this type produced before the field
    /// existed — the reading a file's own tokens support and nothing more.
    ///
    /// **Two consumers, one value**, and that is why the type is the parser's `MacroEnvironment` rather than a
    /// trait object: the *parse* reads it through `ParserConfig::with_macros_from_includes` (which is what lets a
    /// rule take `_STD addressof(*p)` as one qualified name when `_STD` is `::std::`), and the *scope walk*
    /// reads it through [`crate::sema::scopes::MacroBodies`] (which is what opens `std` from `_STD_BEGIN`'s
    /// `namespace std {`). A second value for either would be a second answer to the same question.
    bodies: Option<&'a dyn cpp_parser::MacroBodies>,
    /// The **same evidence**, for the reader that wants the parser's questions rather than the scope walk's one:
    /// `ParserConfig::with_macros_from_includes` takes a [`cpp_parser::MacroFacts`], and a `dyn MacroBodies` is not
    /// one. Both point at the single value the caller handed to [`FileIndexer::with_macro_bodies`], so the parse and
    /// the scope walk cannot be given two different environments — which is the whole reason this type takes a body
    /// reader at all.
    ///
    /// A **unit's timeline** ([`crate::MacroView`]) is such a value: it answers the parser's questions positionally
    /// out of one walk, where the alternative was materialising a map per file.
    macro_facts: Option<&'a dyn cpp_parser::MacroFacts>,
    /// Macro facts whose directive sits at one of these offsets are left out of the summary — the unit walk's own
    /// decision about which `#define`s a compiler would have read. See [`FileIndexer::without_these_macros`].
    dead_macros: Vec<usize>,
    /// **What the compilation defines**, which no file in the closure knows: `__cplusplus` and the rest of the
    /// compiler's own names. See [`FileIndexer::with_seed`].
    seed: Option<&'a crate::Marked>,
    /// The includes a scan already resolved — see [`FileIndexer::scan_includes`]. Resolving an include is a
    /// filesystem search, so a caller that has done it once passes the answers along instead of paying twice.
    scanned: Option<&'a ScannedIncludes>,
    /// **The file's directives, read by someone else** — see [`FileIndexer::with_directives`].
    directives: Option<&'a FileSummary>,
}

/// The `#include`s of one file, found and resolved **before** its parse — see [`FileIndexer::scan_includes`].
#[derive(Debug, Default)]
pub struct ScannedIncludes {
    /// By the offset the directive starts at. The directive itself is kept too, so that an answer is only reused
    /// for the same include: a scan that read a line differently from the parser would find its answer refused, not
    /// wrongly used.
    found: std::collections::HashMap<
        usize,
        (
            crate::preprocess::directive::IncludeForm,
            Box<str>,
            bool,
            Option<PathBuf>,
        ),
    >,
    order: Vec<usize>,
}

impl ScannedIncludes {
    /// The resolved targets, in the order the file writes them.
    pub fn targets(&self) -> Vec<PathBuf> {
        self.order
            .iter()
            .filter_map(|at| self.found.get(at)?.3.clone())
            .collect()
    }

    fn resolved(
        &self,
        at: usize,
        include: &crate::preprocess::directive::Include,
    ) -> Option<Option<PathBuf>> {
        let (form, target, is_next, resolved) = self.found.get(&at)?;
        (*form == include.form && **target == *include.target && *is_next == include.is_next)
            .then(|| resolved.clone())
    }
}

impl<'a, F: FileProvider> FileIndexer<'a, F> {
    pub fn new(files: &'a F, config: &'a CompilerConfig) -> Self {
        FileIndexer {
            files,
            config,
            bodies: None,
            macro_facts: None,
            dead_macros: Vec::new(),
            seed: None,
            scanned: None,
            directives: None,
        }
    }

    /// **The file's directive reading, when the caller already has it.**
    ///
    /// [`FileIndexer::index_the_readings`] needs three things from one file's text: the rendering to parse, the
    /// tokens it was rendered from, and the directives the rendering consumed. Only the first two have to be
    /// produced fresh — the third is a lex, a directive scan, an evaluation of every conditional and a filesystem
    /// search per `#include`, and a caller that has already paid for it (the store remembers it: see
    /// [`SummaryStore::directive_summary`](crate::SummaryStore::directive_summary)) hands it over instead.
    ///
    /// Same text, or the same answer as reading it again: this is the file's own `#define`s, `#include`s and
    /// conditional regions, none of which any other file's environment can change.
    pub fn with_directives(mut self, directives: Option<&'a FileSummary>) -> Self {
        self.directives = directives;
        self
    }

    /// Index with includes a scan already resolved, so that the parse does not search for them a second time.
    pub fn with_scanned_includes(mut self, scanned: &'a ScannedIncludes) -> Self {
        self.scanned = Some(scanned);
        self
    }

    /// The same, for a caller that may or may not have run the scan — `None` leaves the sweep to find the
    /// `#include`s itself, which is the same answer one search later.
    ///
    /// One method rather than a `match` at each call site, because "the scan is optional" is a property of this
    /// builder and not of the callers: [`crate::SummaryStore::prepare`] has no wave to feed and skips it, and
    /// [`crate::SummaryStore::prepare_closure`] needs it. See that pair for the measurement.
    pub fn with_scanned_includes_opt(mut self, scanned: Option<&'a ScannedIncludes>) -> Self {
        self.scanned = scanned;
        self
    }

    /// Index with what the file's includes say about the macros it invokes.
    ///
    /// The one piece of evidence a summary can contain that is **not** in the file it describes: `_STD_BEGIN`'s
    /// `namespace std {` is in `yvals_core.h`, and every declaration in MSVC's `<vector>` is scoped by it. See
    /// [`crate::summary::MacroScopeReading`], which is where the reading and the body behind it are kept.
    ///
    /// The same evidence, for a caller that **already holds it as two trait objects**.
    ///
    /// Generic over the reader rather than taking a `dyn` one, because the two traits it has to satisfy are
    /// unrelated as *trait objects* (`MacroFacts` implies `MacroBodies` through a blanket impl, which the compiler
    /// cannot see through `dyn`): the call site passes a concrete reader — a materialised `MacroEnvironment`, or a
    /// [`crate::MacroView`] into a unit's timeline — and both coercions happen here.
    pub fn with_macro_bodies<T: cpp_parser::MacroFacts>(mut self, bodies: &'a T) -> Self {
        self.bodies = Some(bodies);
        self.macro_facts = Some(bodies);
        self
    }

    /// **What the compilation itself defines** — `-D`s, `-std=`, and the compiler's own several hundred names.
    ///
    /// Here for one question, and it is the question this type could not previously answer: *is `__cplusplus`
    /// defined?* A file's closure knows what its includes define, and the answer for a name the **compiler**
    /// predefines is nowhere in that closure. Measured on `vcruntime.h`, whose `#ifdef __cplusplus` decides
    /// `_STL_LANG`: the closure answered "does not know it", so the branch came out false, so `_STL_LANG` was `0L`
    /// while `__cplusplus` and `_MSVC_LANG` were both `202400L`.
    ///
    /// The same value the store was seeded with (`SummaryStore::with_macros`), so that there is one answer to what
    /// the compilation defines rather than two.
    pub fn with_seed(mut self, seed: &'a crate::Marked) -> Self {
        self.seed = Some(seed);
        self
    }

    /// **`#define`s the unit's walk decided are not compiled**, by directive offset.
    ///
    /// The decision belongs to the walk, which evaluates each guarded fact against the unit's own state — the same
    /// evaluation the cook uses, and the only one that knows what the compilation defines. This type cannot make it:
    /// it has a file and a `Marked`, and the question (`#ifdef __cplusplus`) is about the *unit*.
    ///
    /// What it does with the answer is **drop those facts**, so that a consumer reading the summary does not have to
    /// decide the region a second time — which it would do with a different environment, and answer differently.
    /// Measured on `vcruntime.h`, which writes `_STL_LANG` once per branch of `#ifdef __cplusplus`: the walk takes
    /// the `_MSVC_LANG` branch and skips the `#else`'s `0L`, while a lookup over the raw facts answers `0L` for a
    /// file the compiler reads as C++20.
    pub fn without_these_macros(mut self, dead: &[usize]) -> Self {
        self.dead_macros = dead.to_vec();
        self
    }

    /// Build the summary of the file at `path`, whose text is `source`.
    ///
    /// `key` is the caller's, because only the caller knows the compilation context — the configuration and the
    /// directory the file sits in. It is stored in the summary rather than recomputed, so that a loaded entry can
    /// be checked against the file it claims to describe.
    ///
    /// # The one part of the key that is *not* the caller's
    ///
    /// `key.content_hash` is **replaced** by the hash of `source`. `source` is the same text that was just parsed,
    /// and no caller can describe it more accurately than hashing it — while a caller that got it wrong would
    /// store a summary under a name that does not describe its own text, which is a wrong answer rather than a
    /// cache miss. The authority is here because the text is here.
    ///
    /// # See also
    ///
    /// [`FileIndexer::includes_of`], which answers the one thing about a file that *other* files' reading waits for —
    /// what it includes — without building any of the rest.
    pub fn index(&self, path: &Path, source: &str, key: SummaryKey) -> FileSummary {
        // Parsed **for the configuration's target**: which compiler's reserved spellings mean what is part of the
        // compilation, not of the text — `__int128` is a type to g++ and a name to cl.exe. See
        // [`CompilerConfig::dialect`], and note that the same value is part of `context_hash`, so a summary
        // written for one target is never read as if it were written for the other.
        //
        // …and **with the include closure's macro bodies when the caller has them**: a rule that takes
        // `_STD addressof(*p)` for one qualified name needs to know that `_STD` is `::std::`, and that body is in
        // a header. Without them the parse is the shape-only reading, which is what a buffer on its own
        // gets and all it can get.
        // **`with_skipped_bodies()` is NOT set here, and it was measured rather than assumed.** The mode exists, is
        // correct, and removes 64% of this crate's internal nodes (`examples/body_weight.rs`); enabling it for this
        // parse made a 126-file closure **no faster** — wall 830 → 821 ms, CPU within run-to-run noise, `parse` down
        // 16% and `sweep` *up* 10% — while costing three capabilities that three tests then failed on (a local has no
        // name entry in the index, another file's local is not the answer, and a check inside a body does not fire).
        //
        // The reason is in the two numbers: node building is about a quarter of `parse`, so
        // removing two thirds of the nodes removes a sixth of the stage; and the walks that
        // dominate — `sweep`, and inside it `facts` — are per-**declaration** and do not care how
        // deep the statements around a declaration were nested.
        //
        // It is left in the parser rather than deleted because the measurement is the interesting object: the next
        // person to read "64% of nodes are bodies" will reach for this, and the number that says it buys nothing
        // should be in front of them. `ParserConfig::skip_bodies` carries the same figures.
        let mut config = ParserConfig::default()
            .with_dialect(self.config.dialect())
            .with_cuda(self.config.cuda())
            .with_language(self.config.language_for(path));
        // **The closure's macros, which the doc on this type promised and this call did not pass.** A file's own
        // `#define`s reach the grammar through the directive walk; one from an included header does not, and the rule
        // that reads `NAME { … }` as a macro needs it: measured on `nlohmann/json.hpp`, `JSON_TRY` is defined in
        // `detail/macro_scope.hpp`, the block was read as a braced initialisation, and the recovery swallowed
        // **333 362 bytes** of `basic_json` — every member after it indexed with no class scope.
        if let Some(facts) = self.macro_facts {
            config = config.with_macros_from_includes(facts);
        }
        let tree = { CppParser::parse(source, config) };
        let summary = { self.index_tree(path, source, &tree, key, true) };
        // **Destroying the tree is work**, and it is timed because it is not free and not obvious: a file's tree is
        // tens of thousands of green nodes held by `Arc`s, and dropping it walks every one of them. On the 138-file
        // project this was the missing third of the cold index after the shape walk was fixed — the stages summed to
        // 6.0 s of a 9.5 s run, and the difference was here.
        {
            drop(tree);
        }

        summary
    }

    /// **The files `source` includes**, resolved — without parsing it.
    ///
    /// The include graph is what decides how much of a project can be read at once, and it is only known by reading:
    /// a file's includes are a product of its text. But they are not a product of its *tree*. A `#include` is a
    /// line, the lexer finds every line that begins with a `#`, and the directive scan reads the ones that are
    /// includes — a pass that runs at the speed of the lexer (a hundred and fifty megabytes a second) where the parse
    /// that follows it is an order of magnitude slower. So a caller that wants to start reading a header's includes
    /// **before it has finished parsing the header** can: this is the answer `summary.includes` will hold, obtained
    /// early.
    ///
    /// It is the same answer, not an approximation of it — the same directives, the same resolver, the same search
    /// path and the same directory — which is what lets a caller act on it: every file named here is a file
    /// `index` will record as an include of this one. Order is the text's, and a target the search did not find is
    /// simply not in the list (the summary records it as unresolved).
    pub fn includes_of(&self, path: &Path, source: &str) -> Vec<PathBuf> {
        self.scan_includes(path, source).targets()
    }

    /// [`FileIndexer::includes_of`], keeping the resolutions so that [`FileIndexer::with_scanned_includes`] can hand
    /// them to the parse that follows — a search of the include path is paid for once, not once per pass.
    pub fn scan_includes(&self, path: &Path, source: &str) -> ScannedIncludes {
        let (mut tokens, _) = cpp_parser::lex(source, &cpp_parser::LexerConfig::default());
        fold_quoted_header_names(source, &mut tokens);

        let mut interner = PathInterner::new(cfg!(windows));
        // **This file's compilation, not the project's** — see `CompilerConfig::for_file`.
        let per_file = self.config.for_file(path);
        let resolver = IncludeResolver::new(self.files, &per_file);
        let directory = path.parent().unwrap_or(Path::new("."));

        let mut scanned = ScannedIncludes::default();
        for spanned in crate::preprocess::directive::scan_directives(source, &tokens) {
            let Directive::Include(include) = &spanned.directive else {
                continue;
            };
            let Some(fact) = include_fact(
                &spanned.directive,
                spanned.line,
                directory,
                &resolver,
                &mut interner,
                None,
            ) else {
                continue;
            };

            let at = spanned.range.start_offset;
            scanned.found.insert(
                at,
                (
                    include.form,
                    include.target.clone(),
                    include.is_next,
                    fact.resolved,
                ),
            );
            scanned.order.push(at);
        }
        scanned
    }

    /// **Index a file through its cooked stream** — the reading a compiler would parse, with every range turned
    /// back into a position in the file.
    ///
    /// The tree is built from `rendered.text` (a rendering, whose offsets are not file offsets), so this indexes
    /// the rendering and then answers for every range through
    /// [`FileSummary::map_into_the_file`](crate::FileSummary::map_into_the_file). What comes out is a summary of
    /// the same *shape* as one from the file's own text, describing the program a compiler sees instead of the
    /// text the file says: `DECLARE_HANDLE(HWND)` declares `HWND` here and declares nothing there, and a name
    /// inside a branch nobody takes is declared there and not here.
    ///
    /// Two readings rather than one replacement, and that is the architecture's split rather than a limitation:
    /// the raw summary answers "what is written in this file" (every branch, every macro body — what a reader
    /// editing the file sees) and this answers "what is compiled" (what the editor's *other* features must agree
    /// with). See `examples/cooked_index.rs` for the measurement of how far apart they are.
    ///
    /// The rendering is the caller's because the caller cooked the stream: what to define before it, and which
    /// file's environment to use, are compilation decisions this type has no way to make.
    ///
    /// # The errors come back too, and placed
    ///
    /// A rendering is the text a compiler parses, so what the parser says *about it* is the honest answer to "does
    /// this file compile" — and it is a strictly better answer than the file's own text gives, because a shape the
    /// file writes as a macro call stops being a guess once the macro is expanded, and a declaration in a branch
    /// nobody takes is not there at all. So the errors are not discarded here: each one is asked of the same map
    /// every fact's range goes through ([`crate::RenderedCooked::reported_span`], whose answer is always a place in
    /// this file — the invocation when a macro produced the text), and a rendering error that **cannot** be placed
    /// here is counted rather than reported against a text the reader cannot see.
    pub fn index_rendering(
        &self,
        path: &Path,
        rendered: &crate::preprocess::cooked::RenderedCooked,
        key: SummaryKey,
    ) -> crate::IndexedRendering {
        // **The text this reading is built from**, written out when `CPPLS_DUMP_RENDERING_DIR` names a directory.
        //
        // A parse that goes wrong only here cannot be seen in `inspect tree`, which reads the file's own text, and
        // `Session::render_the_unit` is a different rendering (measured: correct for the 28-line reproducer in
        // `docs/buglist.md` §31, while the summary this function builds is wrong). So the one text that matters gets a
        // way out, off unless asked for, like this crate's other traces.
        if let Some(directory) = crate::probes::dump_rendering_dir() {
            let _ = std::fs::create_dir_all(directory);
            let name = path
                .file_name()
                .map(|name| name.to_string_lossy().into_owned())
                .unwrap_or_else(|| "unit".to_string());
            let _ = std::fs::write(directory.join(format!("{name}.rendering")), &rendered.text);
        }
        // **The stream is already cooked**, so there is nothing for a macro environment to add and a great deal for
        // it to get wrong: its answers are positional in the original file's coordinates while the parser reads the
        // rendering's. See the same note in [`FileIndexer::index`].
        let config = ParserConfig::default()
            .with_dialect(self.config.dialect())
            .with_cuda(self.config.cuda())
            .with_language(self.config.language_for(path));
        let tree = { CppParser::parse(&rendered.text, config) };
        let mut summary = { self.index_tree(path, &rendered.text, &tree, key, true) };
        let report = { summary.map_into_the_file(rendered) };

        // The tree's errors, each asked of the map. `reported_span` answers for a node's whole range — from the first
        // token it covers to the last — and `reported_at` for the span an offset falls in, which is the fallback for
        // an error with no token of its own (the parser can report a range that covers nothing).
        let mut diagnostics = Vec::new();
        let mut unplaced = 0usize;
        for error in tree.get_errors() {
            let range = cpp_parser::source_range(error.range);
            let placed = rendered
                .reported_span(range)
                .or_else(|| rendered.reported_at(range.start_offset));
            match placed {
                Some(range) => diagnostics.push(crate::CookedDiagnostic {
                    range,
                    message: error.message.clone(),
                }),
                None => unplaced += 1,
            }
        }

        crate::IndexedRendering {
            summary,
            rendered: std::sync::Arc::new(rendered.clone()),
            mapped: report,
            diagnostics,
            unplaced,
        }
    }

    /// **Both readings of one file, as the one summary the index holds** — the composition
    /// [`FileIndexer::index_rendering`] and [`FileIndexer::directive_summary`] exist for.
    ///
    /// A file is tokenized and rendered, and the parser reads **only the rendering**; the directives the rendering
    /// consumed are read from the tokens. That is the whole of it, and this function is the only place the two halves
    /// are put together — deliberately, because every caller that took one without the other got a summary that
    /// answered half a file:
    ///
    /// ```text
    /// index_rendering alone     the declarations a compiler reads, and NO #define, #include or region
    /// directive_summary alone   the directives, and NO declarations
    /// both, here                what the file declares *and* what it directs
    /// ```
    ///
    /// The first line is not a smaller answer, it is a wrong one, and the cost of it is written on
    /// [`crate::FileSummary::take_the_directives_of`]: a header whose `#define`s are missing from its summary is a
    /// header whose includers render with `_STD_BEGIN` unexpanded.
    ///
    /// `source` is the file's **own text** — tokenized, never parsed. `key` describes the compilation; its
    /// `content_hash` is replaced by the hash of `source`, exactly as [`FileIndexer::index`] does, because the text is
    /// what is here and no caller can describe it more accurately than hashing it. (`index_rendering` cannot: the text
    /// it is given *is* the rendering, and a summary filed under the rendering's hash is filed under a name that
    /// describes no file — the store's re-read guard compares that hash, and would refuse every reading this builds.)
    pub fn index_the_readings(
        &self,
        path: &Path,
        source: &str,
        rendered: &crate::preprocess::cooked::RenderedCooked,
        key: SummaryKey,
    ) -> crate::IndexedRendering {
        let mut indexed = { self.index_rendering(path, rendered, key) };
        // **The directive half, unless the caller read it already** — see [`FileIndexer::with_directives`]. The
        // order is the architecture's (`directives → unit → parse`), and the caller that needed the directives *first*
        // — to know whether it could walk a timeline at all — is exactly the one that can hand them over.
        let directed = match self.directives {
            Some(directives) => directives.clone(),
            None => self.directive_summary(path, source),
        };
        indexed.summary.take_the_directives_of(directed);
        indexed.summary.key = key;
        indexed.summary.key.content_hash = content_hash(source);
        indexed
    }

    /// **Parse a unit's rendering once, and file the facts under the files they stand in.**
    ///
    /// This is the reading the plan calls *the unit reading*, and it is one step further than
    /// [`FileIndexer::index_rendering`]: that one indexes a **single file's** rendering and maps the ranges back
    /// into that file, while this indexes the **whole program's** rendering — the stream
    /// [`crate::TranslationUnit::cook_the_unit`] stitches in include order — and splits what it finds by the file
    /// each declaration was written in.
    ///
    /// # What it buys
    ///
    /// The index holds "what the compiler saw" for **every file in the program**, including headers nobody has
    /// opened. Without it a header's cooked facts exist only if some request happened to name the file
    /// ([`crate::Session::want_cooked_reading`]), so a cross-file answer about `std::string`'s members depends on
    /// whether a reader had looked at `<xstring>` — a difference no answer should have.
    ///
    /// # The mapping, and what is dropped
    ///
    /// A rendering's offsets are not file offsets, so every range goes back through
    /// [`crate::RenderedUnit::written_span`], which answers with the place a reader can act on: a token the file
    /// wrote keeps its own range, and one that came out of a macro body answers with the **outermost call site**.
    /// A fact whose **name** and whose **range** come out in different files is dropped and counted — half in one
    /// file and half in another is not "a bit less", it is a fact about nothing (the same rule
    /// [`crate::FileSummary::map_into_the_file`] applies per file).
    ///
    /// # Fences, and what changed about them
    ///
    /// One parse of the whole program lets one file's mistake become every later file's: a scope the parser opens
    /// in one file and does not close there stays open, and everything spliced after it is *inside*. The measured
    /// case is `CodeAnalysis/sourceannotations.h`, whose `REPEATABLE [attribute] struct X { … };` the parser reads
    /// as an expression with a lambda body and never closes — so the rest of the program, `<string>` included,
    /// became the body of a lambda, or (before this) sat in `vc_attributes::` for want of a `}`.
    ///
    /// So each parse is checked for a brace paired with a brace of a **different** file (a scope that opens and
    /// closes in one file — even around an `#include` — is not one), and the check is *repaired* rather than
    /// *punished*:
    ///
    /// * the pairing is **neutralised in place** ([`crate::RenderedUnit::neutralized`]): the two brace tokens are
    ///   replaced by markers that pair with nothing, and every other byte of every file stays where it was. The
    ///   result is the same length as the original, so the original span table still answers for every range and a
    ///   fact found in the repaired text is filed under the file that wrote it — which is what makes one parse
    ///   enough;
    /// * the file whose brace had to be given up is parsed **on its own as well** ([`crate::RenderedUnit::only`]),
    ///   so what it declares is filed with whatever mistakes its own parse makes — and those mistakes end at the
    ///   end of the file;
    /// * the repair is **counted** ([`crate::IndexedUnit::repaired`]) and named ([`crate::IndexedUnit::quarantined`]),
    ///   so the cost is visible. It is not a reason to file nothing.
    ///
    /// # What this replaces, and the measurement that asked for it
    ///
    /// The version before this one **removed the leaking file's tokens from the program** and refused to file the
    /// reading at all if a crossing survived three rounds. Both halves of that are the failure mode the plan's §4
    /// names: *"no layer may give up an answer it already has because it is unsure about something else."* A file
    /// that leaked one brace lost every declaration in it, and a program that still crossed after the removal lost
    /// **all of them** — which is how `std::format` had no members while the file that declares them was in the
    /// program, and why `members_of(std::string)` could answer `NotDeclaredHere` about a header that was read.
    ///
    /// Supplying the missing `}` in the leaking file's place was tried before that and does not hold — the parser
    /// is as likely to spend a supplied closer on something inside the leak. That is an argument about *adding* a
    /// token; this is the other direction, and it is sound for a reason the other one is not: a brace that the
    /// parser paired across two files is a brace whose pairing is already wrong, so removing **that** pairing takes
    /// nothing away that was right.
    ///
    /// # The other gate, and why this one had to be repaired first
    ///
    /// There were **two** all-or-nothing gates, and this function is the second. The first was one layer down, in
    /// the cook ([`crate::RenderedUnit::unbalanced`]): a file whose own text does not balance its braces had its
    /// tokens **left out of the stream** before any parse happened, so the imbalance never reached here to be
    /// repaired. That gate is now gone as well — the text goes in and is named — and the consequence is worth being
    /// explicit about, because it makes this function **load-bearing rather than an improvement**:
    ///
    /// ```text
    /// before:  the unbalanced file's tokens were dropped, so the stream balanced by construction
    /// now:     the stream carries the imbalance, and only the repair below keeps the file after it
    ///          out of the leaked scope
    /// ```
    ///
    /// So a change that made `brace_crossings` miss an unclosed-scope crossing would be a regression that no
    /// longer hides behind the cook. `tests/translation_unit.rs`'s
    /// `a_file_that_does_not_balance_still_contributes_its_tokens` pins the cook's half (the stream is left
    /// unbalanced on purpose) and the session's
    /// `a_file_that_does_not_balance_its_braces_is_named_and_still_read` pins this half (the file after it is still
    /// scoped by its own namespace, *and* the unbalanced file kept its declarations).
    pub fn index_unit_rendering(
        &self,
        root: &Path,
        stream: &crate::RenderedUnit,
        key: SummaryKey,
    ) -> crate::IndexedUnit {
        // Built afresh for each parse: a configuration is consumed by the parser it is given to.
        //
        // **No macro environment** — see the note in [`FileIndexer::index`], and note that this is the one parse
        // where it would have been most tempting and most wrong: `stream.text` is a *concatenation of every file's
        // rendering*, so an offset into it is a coordinate no file in the unit has.
        let config = || {
            ParserConfig::default()
                .with_dialect(self.config.dialect())
                .with_cuda(self.config.cuda())
                // **The language the unit is compiled as.** A translation unit is one language, and `root` names it: a
                // `main.c` whose stream writes `struct T *new = …` must be read with C's keyword table, or the
                // declaration is an error and the whole program is filed from a recovery tree. See
                // `CppLexer::name_to_kind`.
                .with_language(self.config.language_for(root))
        };

        // **One parse, of the stream the caller cooked.**
        //
        // There used to be a fence here: the stream was checked for a brace the parse paired across two files, the
        // pair was neutralised, and the files involved were read on their own as well. It is gone, and the reason is
        // the plan's §3.0 — *"真正做预处理之后,解析器看不到 `MacroCall`"*.
        //
        // A crossing needs the parser to pair a brace in one file with a brace in another, and the parser can only do
        // that if the text it is given has braces whose file it cannot tell. Unparsed macro invocations were where
        // they came from: `_STD_BEGIN … _STD_END`, `extern "C" { … }` inside a body, the whole family of
        // open-a-scope-in-a-header macros. **This stream has none of them** — [`crate::RenderedUnit`] is the cooked
        // text, so every macro is already replaced by what it expands to, and `{`/`}` in it are the braces the
        // program has. The processor no longer sees a macro call, so it no longer pairs a brace across a file for a
        // reason that is not in the program.
        //
        // # What is kept, and what it costs to keep
        //
        // [`crate::RenderedUnit::unbalanced`] is still recorded: a file whose *own* text does not balance its braces
        // is a fact about the input, and naming it is the plan's rule 3. What is gone is the **repair**, and with it
        // the two counters the repair needed (`repaired`, `uncured`) and the per-file second parse. A file is read
        // once, by the one parse that reads the program.
        //
        // # If a crossing is seen again
        //
        // It would mean a brace pair really is being made across two files by a stream that has no macro invocations
        // in it — a genuine parser defect, and one that should be fixed **in the parser** rather than absorbed here.
        // The place to look first is a file whose text does not balance: `RenderedUnit::unbalanced` names them, and
        // that list is the honest starting point. Absorbing it a second time would be exactly the "越走越远的
        // workaround" this milestone exists to delete.
        // **The whole stream, its file boundaries and its file list**, when a dump directory is named: the only way
        // to see which file's text a wrong scope came from — the rendering has no file markers in it, and the
        // boundaries are what say where one file stops.
        if let Some(directory) = crate::probes::dump_rendering_dir() {
            let _ = std::fs::create_dir_all(directory);
            let _ = std::fs::write(directory.join("unit.stream"), &stream.text);
            let boundaries: Vec<String> = stream
                .file_boundaries()
                .iter()
                .map(|at| at.to_string())
                .collect();
            let _ = std::fs::write(directory.join("unit.boundaries"), boundaries.join("\n"));
            let files: Vec<String> = stream
                .files
                .iter()
                .map(|path| path.to_string_lossy().into_owned())
                .collect();
            let _ = std::fs::write(directory.join("unit.files"), files.join("\n"));
        }

        let parsing = std::time::Instant::now();
        let tree = {
            // **And where one file's text ends and the next begins**, which is the parser's half of "a scope may not
            // cross a file boundary". `stream` has known it all along — [`crate::RenderedUnit::file_boundaries`] is
            // the first token of each file after the first — and nothing passed it on until now, which is why a
            // header that opens a `namespace` and never closes it held every file spliced after it. The note above
            // is the same rule from the other side: the repair this replaces was deleted on purpose, and the parser
            // is where it belongs.
            CppParser::parse(
                &stream.text,
                config().with_file_boundaries(stream.file_boundaries()),
            )
        };

        let parsed = parsing.elapsed();
        #[cfg(feature = "perf-probe")]
        crate::perf::mark("parse");
        let indexing = std::time::Instant::now();
        let summary = { self.index_tree(root, &stream.text, &tree, key, false) };
        #[cfg(feature = "perf-probe")]
        crate::perf::mark("index_tree");
        if crate::probes::units() {
            eprintln!(
                "[unit] parse {:>6.1} ms  facts {:>6.1} ms  {} file(s), {} byte(s)",
                parsed.as_secs_f64() * 1000.0,
                indexing.elapsed().as_secs_f64() * 1000.0,
                stream.files.len(),
                stream.text.len()
            );
        }

        let mut files: Vec<(std::path::PathBuf, crate::CookedFile)> = stream
            .files
            .iter()
            .map(|path| (path.clone(), crate::CookedFile::default()))
            .collect();
        let mut unplaced = 0usize;
        let errors = tree.get_errors().len();

        file_what_was_found(
            summary.declarations,
            &tree,
            stream,
            &mut files,
            &mut unplaced,
        );
        #[cfg(feature = "perf-probe")]
        crate::perf::mark("files");

        // **One entry per file, however many times the walk entered it.** A preprocessor re-reads an included file
        // every time it is included — `bits/version.h` is the shape, unguarded and included by every libstdc++
        // header — so a unit's stream holds one *slice* per entry, and the second slice is usually empty (the
        // file's own guard is false). `files` is per slice, which is right for the tokens and wrong for the answer:
        // the caller files one reading per path, so a duplicate would replace the first with an empty one. Merged
        // here, in the order the entries happened, and the counters summed.
        //
        // **A declaration is merged by where it is written, not concatenated.** A position in a file names one
        // declaration however many times the stream arrived at it, and the answer has to say so: a stream that held
        // one header more than once — eighteen copies of `CodeFormatCore/Format/Types.h`, built while a decoded
        // summary had lost `visit_once` — gave the class **108 members, 18 of them named `EndLine`**, one per copy of
        // the same declaration at the same offset, and the hover drew one line for each. The same rule for a
        // `#define`, whose name range is the position that names it.
        let mut merged: Vec<(std::path::PathBuf, crate::CookedFile)> =
            Vec::with_capacity(files.len());
        let mut where_to: std::collections::HashMap<std::path::PathBuf, usize> =
            std::collections::HashMap::new();
        // The sites each merged entry already holds, parallel to `merged`.
        let mut declared: Vec<std::collections::HashSet<(usize, usize, usize)>> = Vec::new();
        let mut defined: Vec<std::collections::HashSet<(usize, usize)>> = Vec::new();
        for (path, cooked) in files {
            match where_to.get(&path) {
                Some(&index) => {
                    let held = &mut merged[index].1;
                    for fact in cooked.declarations {
                        let site = (
                            fact.range.start_offset,
                            fact.range.length,
                            fact.name_range.start_offset,
                        );
                        if declared[index].insert(site) {
                            held.declarations.push(fact);
                        }
                    }
                    for fact in cooked.macros {
                        if defined[index].insert((fact.range.start_offset, fact.range.length)) {
                            held.macros.push(fact);
                        }
                    }
                    held.diagnostics.extend(cooked.diagnostics);
                    held.unplaced += cooked.unplaced;
                }
                None => {
                    where_to.insert(path.clone(), merged.len());
                    declared.push(
                        cooked
                            .declarations
                            .iter()
                            .map(|fact| {
                                (
                                    fact.range.start_offset,
                                    fact.range.length,
                                    fact.name_range.start_offset,
                                )
                            })
                            .collect(),
                    );
                    defined.push(
                        cooked
                            .macros
                            .iter()
                            .map(|fact| (fact.range.start_offset, fact.range.length))
                            .collect(),
                    );
                    merged.push((path, cooked));
                }
            }
        }
        let files = merged;

        crate::IndexedUnit {
            files,
            unplaced,
            tokens: stream.len(),
            files_with_tokens: stream.files_with_tokens(),
            missing: stream.missing,
            unbalanced: stream.unbalanced.clone(),
            braces: stream.braces,
            errors,
        }
    }

    /// [`FileIndexer::index`] for a caller that already has the tree.
    ///
    /// Parsing twice is the most expensive thing this layer can be asked to do, and an editor usually has the tree
    /// already — it is what it is displaying.
    pub fn index_tree(
        &self,
        path: &Path,
        source: &str,
        tree: &CppSyntaxTree,
        key: SummaryKey,
        // **Are the declarations inside function bodies wanted?** See `build_facts`: a per-file reading needs them, a
        // program's reading does not.
        keep_locals: bool,
    ) -> FileSummary {
        // The text this summary is built from, when `CPPLS_DUMP_RENDERING_DIR` names a directory — the companion of the
        // same hook in [`FileIndexer::index_rendering`], and the only way to see which reading a wrong answer came
        // from when the file's own text parses correctly.
        if let Some(directory) = crate::probes::dump_rendering_dir() {
            let _ = std::fs::create_dir_all(directory);
            let name = path
                .file_name()
                .map(|name| name.to_string_lossy().into_owned())
                .unwrap_or_else(|| "unit".to_string());
            let _ = std::fs::write(directory.join(format!("{name}.parsed")), source);
        }
        // See `index`: the content part of the key is the text, always. The caller supplies the part that
        // describes the *compilation* — the configuration and the directory the file sits in.
        //
        // Not timed here: the caller that asked for the build has timed this same hash already
        // (`SummaryStore::get` does it to look the entry up), and timing it twice would count it twice.
        let key = SummaryKey::new(content_hash(source), key.context_hash);

        let root = tree.get_red_root();

        let preprocessing = {
            // **With what the compilation already knows**, so a `#define` in a branch nobody compiles is not
            // recorded: `vcruntime.h` writes `_STL_LANG` once per branch of `#ifdef __cplusplus`, the last of them
            // `0L`, and a table that keeps all three answers `0L` for a file compiled as C++20. See
            // [`preprocess_with`], which is where the rule and its cost are stated.
            match self.seed {
                Some(seed) => {
                    crate::preprocess::preprocess_with_a_seed(source, tree.get_tokens(), seed)
                }
                None => crate::preprocess::preprocess(source, tree.get_tokens()),
            }
        };
        // The same evidence object for both readers — see the field's note. The cast is the point: the scope walk
        // asks the trait, the parse asked the concrete type, and there is one value behind both.
        let evidence: &dyn cpp_parser::MacroBodies = match self.bodies {
            Some(bodies) => bodies,
            None => &crate::sema::scopes::NoMacroBodies,
        };
        let scoping = std::time::Instant::now();
        let scopes = {
            let built = build_scopes_with(&root, evidence, keep_locals);
            #[cfg(feature = "perf-probe")]
            crate::perf::mark("scopes");
            built
        };
        let scopes_ms = scoping.elapsed().as_secs_f64() * 1000.0;
        // The diagnostics, as ranges, for the one field a fact takes from them rather than from the tree — see
        // [`DeclFact::clean`]. Collected once for the whole file: the parser reports a handful per file, and
        // asking per declaration would be a scan of the list per fact.
        let errors: Vec<cpp_parser::SourceRange> = tree
            .get_errors()
            .iter()
            .map(|error| cpp_parser::source_range(error.range))
            .collect();

        let making = std::time::Instant::now();
        let (mut declarations, mut guards) =
            { build_facts(&scopes, &preprocessing, &root, &errors, keep_locals) };
        if crate::probes::units() {
            eprintln!(
                "[unit]   scopes {:>6.1} ms  facts {:>6.1} ms  ({} fact(s))",
                scopes_ms,
                making.elapsed().as_secs_f64() * 1000.0,
                declarations.len()
            );
        }

        let mut interner = PathInterner::new(cfg!(windows));
        // **This file's compilation, not the project's** — see `CompilerConfig::for_file`.
        let per_file = self.config.for_file(path);
        let resolver = IncludeResolver::new(self.files, &per_file);
        let directory = path.parent().unwrap_or(Path::new("."));

        // The includes are their own stage because **resolving one is a filesystem search**, per file, per pass —
        // the one step here that is not proportional to the text but to the search path. Measured on the 138-file
        // project, this is where most of the sweep goes.
        let (mut macros, mut includes) = {
            let macros: Vec<MacroFact> = preprocessing
                .directives
                .iter()
                .filter_map(macro_fact)
                .collect();

            // The interner is local: resolving an include mints an id as a side effect, and the id is discarded
            // because a summary stores the *path*. A `FileId` is an index into a run's interner and means nothing to
            // whoever reads the summary back.
            let includes: Vec<IncludeFact> = preprocessing
                .directives
                .iter()
                .filter_map(|spanned| {
                    include_fact(
                        &spanned.directive,
                        spanned.line,
                        directory,
                        &resolver,
                        &mut interner,
                        self.scanned,
                    )
                })
                .collect();

            (macros, includes)
        };

        // **What the walk decided is not compiled**, and this is where that decision is applied: a `#define` under a
        // conditional a compiler does not take is not a definition any consumer should see, and a summary that keeps
        // it makes the consumer decide the region a second time — with a different environment, and differently. See
        // [`FileIndexer::without_these_macros`] and [`crate::TranslationUnit::dead_macros`].
        //
        // It has to happen **here**, on the facts, and not inside the preprocessing: the offsets come from a walk of
        // the whole translation unit, which this type has never seen. The list is per file and holds the handful of
        // guarded `#define`s a real header writes per configuration, so the linear test is the whole cost.
        if !self.dead_macros.is_empty() {
            macros.retain(|fact| !self.dead_macros.contains(&fact.range.start_offset));
        }

        // Every kind of fact carries a guard, and they are assigned together rather than per kind: the sweep is
        // over *offsets*, and running it once per fact list would rebuild the region list each time. An include's
        // guard is the one that earns its keep — it is what a cross-file lookup reads to decide whether a
        // declaration reached through that include is unconditionally in scope — but a `#define` inside an `#if`
        // is the same question about a macro.
        macros.sort_by_key(|fact| fact.range.start_offset);
        includes.sort_by_key(|fact| fact.range.start_offset);

        let mut guarded: Vec<(&mut FactGuard, usize)> = macros
            .iter_mut()
            .map(|fact| (&mut fact.guard, fact.range.start_offset))
            .chain(
                includes
                    .iter_mut()
                    .map(|fact| (&mut fact.guard, fact.range.start_offset)),
            )
            .collect();
        guarded.sort_by_key(|(_, at)| *at);

        let own_guard = {
            assign_guards(&mut guarded, &preprocessing, &mut guards);

            // The file's **own include guard is not a condition**, and this is the step that makes the standard
            // library queryable at all: a header puts its whole body inside `#ifndef _GLIBCXX_STRING`, so without this
            // rule every `#include` written inside a header is "conditional" and every declaration reached through one
            // is `ConditionalCompilation` — measured on the closure of `<string>`, that is *every* cross-file answer
            // there is. See `deguard_the_files_own_guard` for why calling it unconditional is the honest reading.
            //
            // **Read from the tokens, not from the tree** — and the measurement that moved it: `3rd/utf8/include/
            // utf8.h` and `mimalloc/src/bitmap.c` open with a comment, their parse produces a nested `TranslationUnit`
            // and a misplaced `Declaration`, and the tree rule ("is there a top-level child before the `#ifndef` that
            // looks like code") then saw code before a guard that has none — so every declaration in two guarded
            // headers was `ConditionalCompilation`. The token rule is the text's own answer, and the directive
            // summary uses the same one, which is what `examples/directive_oracle.rs` compares.
            let own_guard = own_guard_region_from_tokens(&preprocessing, tree.get_tokens());

            // Stored, not just used here: a *walk* evaluating a condition needs the same rule, and it has only the
            // summary. See `SummaryGuards::own_guard` — a file's own guard is not a condition on anything.
            guards.own_guard = own_guard.map(|region| region as u32);

            // **And whether the file asks to be entered once by pragma**, which is the same scan `detect_guard`
            // already did — kept because the renderer needs to emit the line and has no directives to look at.
            guards.visit_once = preprocessing.directives.iter().any(|spanned| {
                matches!(
                    &spanned.directive,
                    crate::directive::Directive::Pragma { tokens }
                        if tokens.first().is_some_and(|token| token.text() == "once")
                )
            });

            if let Some(region) = own_guard {
                let mut all: Vec<&mut FactGuard> = declarations
                    .iter_mut()
                    .map(|fact| &mut fact.guard)
                    .chain(macros.iter_mut().map(|fact| &mut fact.guard))
                    .chain(includes.iter_mut().map(|fact| &mut fact.guard))
                    .collect();
                deguard_the_files_own_guard(&mut all, region);
            }

            own_guard
        };

        // What the guards above cannot say on their own: whether a `#define` inside an `#if` still *settles* the
        // name whichever branch is taken — the `#ifndef NAME / #define NAME` idiom, which is how the system headers
        // define most of the macros a project uses. It runs after the de-guard step because a fact already
        // `Unconditional` has nothing to settle, and it is told which region the own guard is because the rule it
        // applies nests inside conditionals and must agree with that step about what a file guard means.
        {
            mark_settling_macro_facts(&preprocessing, own_guard, &mut macros);
        }

        // **Header units are resolved in the same stage as includes**, because they are the same filesystem search:
        // `import <vector>;` names a header, and the answer to "which vector" has to be the compiler's answer. See
        // [`modules_of`].
        let modules = { modules_of(&root, directory, &resolver, &mut interner) };

        FileSummary {
            path: path.to_path_buf(),
            key,
            declarations,
            macros,
            includes,
            guards,
            // Where a scope came out of a macro's replacement list rather than out of this file's braces. Taken
            // from the walk rather than recomputed: the walk is the only thing that asked, and asking again here
            // would be a second reader of the same evidence, free to disagree with the scopes it is describing.
            macro_readings: scopes.macro_readings,
            // **Which names this file mentions**, so that a references query can skip it without reading it. Built
            // from the tree the parse just produced — the identifiers are already there, and a filter built from the
            // *text* would count the names inside comments and strings. See [`FileSummary::use_filter`].
            use_filter: crate::summary::use_filter_of(&root),
            modules,
        }
    }

    /// **What a file *directs*, with no parse behind it** — the `#include`s, `#define`s and conditional regions of
    /// a file, in the shape [`crate::TranslationUnit::walk`] reads them.
    ///
    /// # What it is for
    ///
    /// A timeline walk needs, per file, exactly three things: `macros`, `includes`, and `guards` (grepped: the walk
    /// reads nothing else from a [`FileSummary`]). None of the three needs a parse — they come from the lexer and
    /// the directive scanner — so this is the summary a caller can have **before** the file is parsed.
    ///
    /// That is the piece the cold start is missing. `TranslationUnit::walk` requires
    /// `index.summary(file)` for every file of the closure, so an environment exists only *after*
    /// the closure is indexed, which is why the first parse is provisional and why a second pass
    /// has to re-read 1 001 files.
    ///
    /// # The one thing that is not from the directives
    ///
    /// `guards.own_guard` — "is this file's own `#ifndef` its guard" — was answered from the tree, because "is there
    /// code before the `#ifndef`" is a question about declarations. [`crate::guards::detect_guard_from_tokens`]
    /// answers it from the token stream instead: code is a token that is neither trivia nor inside a directive.
    ///
    /// # Why a `FileSummary` and not a smaller type
    ///
    /// Because the walk is written against `&FileSummary` and a second type would mean a second walk. Every field
    /// this function cannot fill is **empty**, and empty is the honest value: no declarations were read, so there
    /// are none. `examples/directive_oracle.rs` compares the three fields the walk uses against the real summary for
    /// every file of a project — that comparison is what says the two readings agree.
    pub fn directive_summary(&self, path: &Path, source: &str) -> FileSummary {
        let (mut tokens, _) = cpp_parser::lex(source, &cpp_parser::LexerConfig::default());
        // **The one thing the parser does to a token stream that a bare lex does not.** A quoted header name is a
        // string literal to the lexer and a header name to a directive, so `scan_directives` never sees
        // `#include "x.h"` unless the name is folded first — found by `examples/directive_oracle.rs`, which reported
        // every quoted include missing and every angled one present. `scan_includes` makes the same call for the
        // same reason.
        fold_quoted_header_names(source, &mut tokens);
        let preprocessing = match self.seed {
            Some(seed) => crate::preprocess::preprocess_with_a_seed(source, &tokens, seed),
            None => crate::preprocess::preprocess(source, &tokens),
        };

        let mut interner = PathInterner::new(cfg!(windows));
        // **This file's compilation, not the project's** — see `CompilerConfig::for_file`.
        let per_file = self.config.for_file(path);
        let resolver = IncludeResolver::new(self.files, &per_file);
        let directory = path.parent().unwrap_or(Path::new("."));

        let (mut macros, mut includes) = {
            let macros: Vec<MacroFact> = preprocessing
                .directives
                .iter()
                .filter_map(macro_fact)
                .collect();
            let includes: Vec<IncludeFact> = preprocessing
                .directives
                .iter()
                .filter_map(|spanned| {
                    include_fact(
                        &spanned.directive,
                        spanned.line,
                        directory,
                        &resolver,
                        &mut interner,
                        self.scanned,
                    )
                })
                .collect();
            (macros, includes)
        };

        // The same decision, the same place — see the note in [`FileIndexer::index_tree`].
        if !self.dead_macros.is_empty() {
            macros.retain(|fact| !self.dead_macros.contains(&fact.range.start_offset));
        }

        // The order `index_tree` does them in, and it matters: the guards are assigned to the facts *before* the
        // file's own guard de-guards them, and the settling rule reads what that left.
        macros.sort_by_key(|fact| fact.range.start_offset);
        includes.sort_by_key(|fact| fact.range.start_offset);

        let mut guards = crate::summary::SummaryGuards::default();
        let mut guarded: Vec<(&mut FactGuard, usize)> = macros
            .iter_mut()
            .map(|fact| (&mut fact.guard, fact.range.start_offset))
            .chain(
                includes
                    .iter_mut()
                    .map(|fact| (&mut fact.guard, fact.range.start_offset)),
            )
            .collect();
        guarded.sort_by_key(|(_, at)| *at);

        assign_guards(&mut guarded, &preprocessing, &mut guards);

        let own_guard = own_guard_region_from_tokens(&preprocessing, &tokens);
        guards.own_guard = own_guard.map(|region| region as u32);
        guards.visit_once = preprocessing.directives.iter().any(|spanned| {
            matches!(
                &spanned.directive,
                crate::directive::Directive::Pragma { tokens }
                    if tokens.first().is_some_and(|token| token.text() == "once")
            )
        });

        if let Some(region) = own_guard {
            let mut all: Vec<&mut FactGuard> = macros
                .iter_mut()
                .map(|fact| &mut fact.guard)
                .chain(includes.iter_mut().map(|fact| &mut fact.guard))
                .collect();
            deguard_the_files_own_guard(&mut all, region);
        }

        mark_settling_macro_facts(&preprocessing, own_guard, &mut macros);

        FileSummary {
            path: path.to_path_buf(),
            // No content or context hash goes in: this summary is never stored or looked up, and a key that looked
            // like a real one would invite exactly that. The walk does not read it.
            key: SummaryKey::new(0, 0),
            declarations: Vec::new(),
            macros,
            includes,
            guards,
            macro_readings: Vec::new(),
            // **From the tokens**, which is what this function has: the filter's contract is that a `false` is
            // certain, and the token stream is the file's whole text — every branch, every macro body. See
            // [`crate::summary::use_filter_of_tokens`].
            use_filter: crate::summary::use_filter_of_tokens(source, &tokens),
            modules: crate::ModuleReading::default(),
        }
    }
}

/// **What a file declares about modules**, read from its tree.
///
/// The same reading [`crate::ModuleScanner`] makes ([`crate::ModuleInfo::from_tree`]), reduced to the three things
/// the *visibility* walk needs and stored in the summary so that it can be read without a tree — see
/// [`crate::ModuleReading`].
///
/// All three resolved-file lists are here for the same reason: **the walk holds summaries and can search nothing**,
/// so a file the walk has to reach has to have been found already. What is *not* here is the edge's direction or its
/// `export`: an `export import` re-exports and a plain `import` does not, and this model records neither — the
/// direction of that omission is stated on [`crate::ModuleReading`].
fn modules_of<F: FileProvider>(
    root: &cpp_parser::CppSyntaxNode,
    including: &Path,
    resolver: &IncludeResolver<'_, F>,
    interner: &mut PathInterner,
) -> crate::ModuleReading {
    let info = crate::ModuleInfo::from_tree(root);

    // **A header unit is a header**, and `import <vector>;` finds it by the same search `#include <vector>` uses —
    // so the same resolver is asked, and a second implementation of "which `vector` did you mean" does not exist to
    // disagree with the compiler. The *resolved path* is what is recorded rather than the spelling: the visibility
    // walk holds summaries and cannot search anything.
    //
    // `None` for a header that cannot be found (no include paths configured, a header outside them) — the walk
    // then knows nothing about that import, which is the honest state and not an empty header unit.
    let header_units: Vec<std::path::PathBuf> = info
        .imports
        .iter()
        .filter_map(|declaration| match &declaration.target {
            crate::ImportTarget::HeaderUnit { name, is_angle } => {
                let include = crate::directive::Include {
                    target: name.to_string().into(),
                    form: if *is_angle {
                        crate::directive::IncludeForm::Angle
                    } else {
                        crate::directive::IncludeForm::Quote
                    },
                    is_next: false,
                };

                resolver
                    .resolve(&include, including, None, interner)
                    .resolved()
                    .map(|resolved| resolved.path.clone())
            }
            _ => None,
        })
        .collect();

    // **A partition of this file's own module**, which is not a module and is not found by an include search:
    // `export import :area;` in `shapes.cppm` means "the `area` partition of `shapes`", and the file that declares
    // it is found by the module naming convention — the same resolution `scan_imports` uses, through the same
    // [`crate::ModuleScanner`], so that "which file is `shapes:area`" has one answer in this crate.
    //
    // It has to be resolved here rather than left to the visibility walk for the reason the walk's own note gives:
    // the walk holds summaries and can search nothing. And it has to be *recorded* because a partition's names are
    // part of the module's interface when the import is an `export import` — measured on the partition fixture,
    // where `rectangle` and `square` answered "nothing declares it" from a file that says `import shapes;` while
    // `perimeter`, declared directly in the interface unit, resolved.
    //
    // A partition whose file cannot be found is **absent**, like an unresolved header unit: that is the honest
    // state — nothing is known about it — rather than an empty partition.
    let partitions: Vec<std::path::PathBuf> = match info.module_name.as_deref() {
        Some(module) if info.has_an_imported_partition() => {
            let mut scanner = crate::ModuleScanner::new(resolver.files(), resolver.config());
            let mut found = Vec::new();

            for declaration in &info.imports {
                let Some(name) = declaration.target.partition_name() else {
                    continue;
                };

                if let crate::ImportOutcome::Resolved(unit) =
                    scanner.resolve_partition(Some(module), name, including, interner)
                    && let Some(entry) = scanner.units().iter().find(|entry| entry.file == unit)
                {
                    found.push(entry.path.clone());
                }
            }

            found
        }
        _ => Vec::new(),
    };

    crate::ModuleReading {
        module: info.module_name,
        partition: info.partition_name,
        // **`is_interface` is `ModuleUnit::is_interface`, not `== InterfaceUnit`.** A partition has two unit kinds
        // and only the interface one is what an `import :part;` reaches — so a reader that asked for the primary
        // interface variant answered `false` for every partition interface unit there is, which is how this was
        // written first. `ModuleUnit` already states the rule (and `exports_to_importers` states the *different*
        // question a module name asks); this is the caller that has to use it.
        is_interface: info.unit.is_some_and(crate::ModuleUnit::is_interface),
        imports: info
            .imports
            .iter()
            .filter_map(|declaration| declaration.target.module_name().map(Box::from))
            .collect(),
        header_units,
        partitions,
    }
}

/// A summary of a file with **no project around it**: every include unresolved, every macro recorded.
///
/// The entry point for a caller that has text and nothing else — a test, or an editor on a file outside any
/// project. Equivalent to a [`FileIndexer`] whose resolver finds nothing, and named separately so that the
/// ordinary case does not have to construct a configuration it is not going to use.
pub fn summarize(path: &Path, source: &str, key: SummaryKey) -> FileSummary {
    /// A provider that has no files, so every include comes out unresolved.
    struct NoFiles;

    impl FileProvider for NoFiles {
        fn read(&self, _path: &Path) -> Option<String> {
            None
        }

        fn exists(&self, _path: &Path) -> bool {
            false
        }
    }

    FileIndexer::new(&NoFiles, &CompilerConfig::default()).index(path, source, key)
}

/// The [`MacroFact`] for a `#define` or an `#undef`, or `None` for every other directive.
///
/// Both are facts about the same name's history, and a query needs both to be answerable: a name `#undef`ed above
/// the cursor is not a macro, and a table that only remembers definitions would point at a `#define` that is no
/// longer in force. See [`crate::MacroKind`].
///
/// `spanned` rather than the bare directive because an `#undef`'s *name* position is not tracked by the directive
/// reader — it keeps the name and no range — so the fact carries the directive's range, which is the line to show
/// a user asking where a macro stops being one.
fn macro_fact(spanned: &SpannedDirective) -> Option<MacroFact> {
    match &spanned.directive {
        Directive::Define(define) => {
            let definition = define.macro_def.as_ref()?;

            Some(MacroFact {
                name: definition.name.to_string(),
                kind: crate::summary::MacroKind::Definition,
                function_like: definition.is_function_like(),
                body: macro_body_shape(definition),
                value: macro_value(definition),
                alias: macro_alias(definition),
                // The *name's* range, not the directive's: "go to macro definition" is a jump to the name a user
                // can see, and a rename edits it. The guard sweep reads this fact's offset too, and the name is
                // inside the same conditional region as the directive that wrote it — a `#define` cannot span an
                // `#endif`.
                range: definition.name_range,
                guard: crate::summary::FactGuard::Unconditional,
                // **Where the body is**, derived from the body's own tokens rather than searched for in the
                // directive's text: `MacroDef::body.tokens` each carry their range, so the span from the first
                // to the last *is* the replacement list. `None` for an empty body (`#define FOO`), which is the
                // ordinary feature flag and has nothing to expand.
                body_range: body_range_of(definition),
                // Filled in by `mark_settling_macro_facts`, which is the only place that knows where the
                // conditionals are; see `MacroFact::settles_the_name`.
                settles_the_name: false,
            })
        }
        Directive::Undef { name: Some(name) } => Some(MacroFact {
            name: name.to_string(),
            kind: crate::summary::MacroKind::Undefinition,
            function_like: false,
            // Nothing to say about a body, and saying `Unknown` is the honest way to say it.
            body: cpp_parser::MacroBody::Unknown,
            // An `#undef` has no value: the name stops being a macro, which is the whole of what it says.
            value: None,
            alias: None,
            // **The directive's own line**, as for an #include: the tree's span runs on through the newline and the
            // comment under it, and a jump to an #undef should land on the line that wrote it.
            range: spanned.line,
            body_range: None,
            guard: crate::summary::FactGuard::Unconditional,
            settles_the_name: false,
        }),
        _ => None,
    }
}

/// The value a condition could read out of a definition, or `None`.
///
/// One integer literal in the body, and nothing else — which is exactly what
/// [`crate::condition::macro_value`] accepts, so the two agree by construction rather than by convention. A
/// function-like macro is not a value at all (`#if F(x)` is not how a macro is asked about), and neither is a body
/// of two tokens, a body that is a name, or an empty body: a condition asking about any of them is `Unknown`, and
/// storing a spelling that no evaluator can use would only make the cache bigger.
fn macro_value(definition: &crate::preprocess::macros::MacroDef) -> Option<Box<str>> {
    if definition.is_function_like() {
        return None;
    }

    let mut significant = definition.body.significant();
    let only = significant.next()?;

    if significant.next().is_some() {
        return None;
    }

    (only.kind == cpp_parser::CppTokenKind::IntegerLiteral).then(|| only.text.as_str().into())
}

/// **The one name a macro's body *is*, when the body is exactly one identifier** — `#define A B`.
///
/// Computed here, where the replacement list is in hand, because a `MacroSummary` cannot answer it later: what it
/// stores of a body is a [`cpp_parser::MacroBody`] (a *shape*, not tokens) and a range into the file the `#define`
/// was written in. The name is the whole of what following the alias needs, and it is one token to read now.
///
/// Why it matters: a condition read against an index answers `#if _STL_LANG > 201402L` only if it learns that
/// `_STL_LANG` is `__cplusplus`, which is itself a macro with a value. `vcruntime.h` writes exactly that, and with
/// the alias unreadable `_HAS_CXX17` never became defined — so every `#if _HAS_CXX17` below it, including the one
/// around `<atomic>` in `<memory>`, was undecidable.
fn macro_alias(definition: &crate::preprocess::macros::MacroDef) -> Option<Box<str>> {
    // `#define A(x) x` used without arguments is a name, not `x`: only an object-like macro aliases another.
    if definition.is_function_like() {
        return None;
    }

    let mut significant = definition.body.significant();
    let only = significant.next()?;

    if significant.next().is_some() {
        return None;
    }

    (only.kind == cpp_parser::CppTokenKind::Identifier).then(|| Box::from(only.text()))
}

/// The region a file's own include guard opens, when it has one.
///
/// `Some(0)` or `None`, and the zero is not a coincidence: [`crate::detect_guard`] only recognises a guard that is
/// the file's **first** conditional, at depth 0, with no declaration before it — so when there is a guard, the
/// first region in the list is the one it opens. `#pragma once` is a guard with no region at all, which is why
/// the answer is an index rather than a boolean.
/// [own_guard_region] for a caller with **no tree** — see [FileIndexer::directive_summary].
fn own_guard_region_from_tokens(
    preprocessing: &crate::FilePreprocessing,
    tokens: &[cpp_parser::CppTokenData],
) -> Option<usize> {
    match crate::guards::detect_guard_from_tokens(&preprocessing.directives, tokens) {
        crate::guards::Guard::Macro(_) => Some(0),
        crate::guards::Guard::PragmaOnce => {
            crate::guards::has_a_macro_guard_from_tokens(&preprocessing.directives, tokens)
                .then_some(0)
        }
        crate::guards::Guard::None => None,
    }
}

/// Treat everything inside a file's own include guard as **unconditional**.
///
/// # Why a guard is not a condition
///
/// A `#if` makes a fact conditional because whether the branch was taken depends on macros this analysis does not
/// have — the fact might be invisible, so a consumer is told `Unknown` rather than `Yes`. A file's **own** guard is
/// the one `#if` where that reasoning does not hold: the condition is `#ifndef _GLIBCXX_STRING`, and *entering the
/// file at all* is what defines `_GLIBCXX_STRING`. Every inclusion of a guarded header that does anything takes
/// the branch; the visits that do not are the ones where the header has already been read, and the declarations
/// are visible from those too.
///
/// So a declaration inside the guard is visible to **any** file that includes the header, which is exactly what
/// `Unconditional` means here, and what it does not mean is "there was no `#if` in the text" — the region is
/// still in [`crate::SummaryGuards::regions`], and the guard macro is still a fact of the file.
///
/// # What it costs, measured
///
/// Without it, the closure of `<string>` answers **every** cross-file query with `ConditionalCompilation`: the
/// standard library's headers guard their bodies, so every `#include` inside one is inside a region.
/// `examples/std_query.rs` is the probe that shows it — 0 of 7 ordinary queries resolved before this rule.
fn deguard_the_files_own_guard(facts: &mut [&mut FactGuard], region: usize) {
    for fact in facts {
        if **fact == FactGuard::Region(region as u32) {
            **fact = FactGuard::Unconditional;
        }
    }
}

/// The shape of a macro's body, in the vocabulary the parser's rules ask about.
///
/// This classifier is the join between the two ends of a macro's life. On one side
/// [`crate::preprocess::macros::MacroBody`] holds the body's **tokens**, because expansion needs them; on the
/// other [`cpp_parser::MacroBody`] is the *shape* the grammar acts on — `Statement` for a macro whose invocation
/// needs no `;`, `Specifier` for one that stands where a declaration specifier goes. Nothing else converts
/// between them, so every macro-shaped reading in the parser ends up guessing; this is the evidence that replaces
/// the guess.
///
/// # How the shape is decided
///
/// By the first and last significant tokens, which is what a reader uses too:
///
/// ```text
/// __declspec(dllexport)      a specifier — call-like, and it is not a statement
/// do { … } while (false)     a statement that brings its own `;`-free block
/// if (x) { … }               a statement
/// ((a) > (b) ? (a) : (b))    an expression
/// int                        a type
/// { … }                      a block, always followed by `{`
/// ```
///
/// The order of the tests is the order the shapes exclude each other: a body that opens with a control keyword or
/// `do` is a statement whatever else is in it, and only a body that is *entirely* a parenthesised expression is an
/// expression — `(a) + (b)` is a sum, and calling a sum an expression is right, while calling `((a) > (b) ? …)` a
/// statement would be wrong.
///
/// `MacroBody::Unknown` is the answer when nothing matches, and it is not a failure: it already rules out the
/// *call* reading, which is most of what a caller gets from knowing a name is a macro.
/// The range of a macro's **replacement list** inside its `#define` — see [`crate::summary::MacroFact::body_range`].
///
/// Derived from the body's own tokens, never searched for: each token carries the range it was lexed at, so the
/// span from the first to the last is the body, whatever spelling the directive used around it.
///
/// **The last *significant* token, because the body keeps trivia and the trivia runs past the list.** The lexer
/// preserves whitespace and comments so a macro's text can be reprinted, and those tokens carry ranges too: taking the
/// last of *all* of them made the body run on into whatever followed it — the doc comment above the next `#define`, or
/// the next directive itself. Measured on a nine-file C corpus: six `macro-parentheses` findings whose bodies were
/// `"corpus"\n\n/* A function-like macro … */\n`, and one `redefinition` for a macro compared against text that was not
/// its body.
///
/// **An empty replacement list is empty, and says so with a zero length.** `#define CORPUS_H` has no body, and the
/// fallback here used to take the trivia after the name — for an include guard followed by a comment, that is the
/// comment block itself. `macro-parentheses` then read the comment as the replacement list, found a `:` in it and
/// reported `CORPUS_H`'s "replacement list" as unparenthesised: a warning a reader gets the first time the header is
/// opened, on the one line of an include guard that could not possibly be wrong. Measured on
/// `C:\Users\zc\Desktop\c-project\include\corpus.h`: the body was 355 bytes, the comment under the guard. A zero-length
/// range keeps `Some`, so the environment and the macro table still agree that the fact has a body, and it slices to
/// `""` — which every body judge already reads as "no replacement list".
///
/// **The start is not narrowed the same way, and that is deliberate.** `body_text` is sliced from this range and the
/// expander hands *its* token slice to the paste operator, whose positions were recorded against the body as written —
/// so changing the start would move every `##` in the project by one token, which is the X-macro paste this interacts
/// with.
fn body_range_of(
    definition: &crate::preprocess::macros::MacroDef,
) -> Option<cpp_parser::SourceRange> {
    let first = definition.body.tokens.first()?;
    let start = first.range.start_offset;
    let end = match definition.body.significant().last() {
        Some(last) => last.range.start_offset + last.range.length,
        None => start,
    };
    Some(cpp_parser::SourceRange::new(
        start,
        end.saturating_sub(start),
    ))
}
fn macro_body_shape(definition: &crate::preprocess::macros::MacroDef) -> cpp_parser::MacroBody {
    use cpp_parser::CppTokenKind;
    use cpp_parser::MacroBody;

    let tokens: Vec<CppTokenKind> = definition
        .body
        .significant()
        .map(|token| token.kind)
        .collect();

    let Some(first) = tokens.first().copied() else {
        // `#define FOO` — a macro that expands to nothing. Used for feature flags, so it is ordinary rather than
        // malformed; with no body there is no shape to report.
        return MacroBody::Unknown;
    };

    // A body that is only a brace is the gtest shape: the invocation is always followed by the block it wrote.
    if first == CppTokenKind::LeftBrace && tokens.last().copied() == Some(CppTokenKind::RightBrace)
    {
        return MacroBody::Block;
    }

    if matches!(
        first,
        CppTokenKind::IfKeyword
            | CppTokenKind::ForKeyword
            | CppTokenKind::WhileKeyword
            | CppTokenKind::SwitchKeyword
            | CppTokenKind::DoKeyword
            | CppTokenKind::ReturnKeyword
            | CppTokenKind::ThrowKeyword
            | CppTokenKind::TryKeyword
            | CppTokenKind::BreakKeyword
            | CppTokenKind::ContinueKeyword
            | CppTokenKind::GotoKeyword
    ) {
        return MacroBody::Statement;
    }

    // A specifier: an attribute, an export marker, a calling convention. Two spellings reach here and they need
    // separate tests, because one is C++ and the other is not:
    //
    // * the specifier *keywords* — `static`, `extern`, `inline` — which no other construct can begin with;
    // * the compiler's own attribute spelling — `__declspec(dllexport)`, `__attribute__((…))` — which is an
    //   identifier followed by a parenthesised group, and therefore shaped exactly like `MAX(a, b)`.
    if is_specifier_like(tokens[0])
        || is_compiler_specifier_macro(&tokens, first_spelling(definition))
    {
        return MacroBody::Specifier;
    }

    // A type: the body is one or two type keywords and nothing else — `#define MY_INT int`. A second *word* rules
    // it out, because `int x` is a declaration and not a type.
    if tokens.iter().all(|kind| is_type_word(*kind)) {
        return MacroBody::Type;
    }

    // An expression: everything in the body is an operand, an operator, or a bracket, and the whole body is
    // parenthesised. The parenthesis test is what separates `((a) > (b) ? (a) : (b))` from `(a) + (b)`, which is
    // also an expression — and both answers are `Expression`, so the test is about *confidence*: a body that is
    // one parenthesised group is an expression whatever is inside it.
    if is_one_parenthesised_group(&tokens) {
        return MacroBody::Expression;
    }

    MacroBody::Unknown
}

/// Is this token only ever a declaration specifier?
fn is_specifier_like(kind: cpp_parser::CppTokenKind) -> bool {
    use cpp_parser::CppTokenKind as K;

    matches!(
        kind,
        K::ExternKeyword
            | K::StaticKeyword
            | K::InlineKeyword
            | K::ConstexprKeyword
            | K::VirtualKeyword
            | K::ExplicitKeyword
            | K::MutableKeyword
            | K::ThreadLocalKeyword
            | K::TypedefKeyword
            | K::FriendKeyword
    )
}

/// Is this token a word that can name a type on its own?
fn is_type_word(kind: cpp_parser::CppTokenKind) -> bool {
    use cpp_parser::CppTokenKind as K;

    matches!(
        kind,
        K::VoidKeyword
            | K::BoolLiteral
            | K::CharKeyword
            | K::ShortKeyword
            | K::IntKeyword
            | K::LongKeyword
            | K::FloatKeyword
            | K::DoubleKeyword
            | K::SignedKeyword
            | K::UnsignedKeyword
    )
}

/// Is this macro body a compiler-specific **specifier** spelling?
///
/// `__declspec(dllexport)` and `__attribute__((visibility("default")))` are what an export macro is written as on
/// the two mainstream compilers, and both are *call-shaped*: an identifier followed by a parenthesised group. They
/// are not C++ at all, so no rule of the grammar could recognise them — but a macro whose body is one of them
/// stands exactly where a declaration specifier does, and that is the fact the parser needs from this classifier.
///
/// Recognised **by name** rather than by shape alone, because the shape is shared with every other function-like
/// macro: `MAX(a, b)` is also an identifier and a parenthesised group, and calling that a specifier would make
/// `MAX(1, 2)` a declaration. The names are the compilers', so the list does not grow with user code.
fn is_compiler_specifier_macro(tokens: &[cpp_parser::CppTokenKind], spelling: &str) -> bool {
    use cpp_parser::CppTokenKind as K;

    if tokens.first().copied() != Some(K::Identifier)
        || tokens.get(1).copied() != Some(K::LeftParen)
        || tokens.last().copied() != Some(K::RightParen)
    {
        return false;
    }

    matches!(
        spelling,
        "__declspec" | "__attribute__" | "__attribute" | "__cdecl" | "__stdcall" | "__fastcall"
    )
}

/// The spelling of a macro body's first significant token, for the tests that have to read it by name.
fn first_spelling(definition: &crate::preprocess::macros::MacroDef) -> &str {
    definition
        .body
        .significant()
        .next()
        .map(|token| token.text.as_ref())
        .unwrap_or("")
}

/// Is the whole body wrapped in one pair of parentheses?
fn is_one_parenthesised_group(tokens: &[cpp_parser::CppTokenKind]) -> bool {
    use cpp_parser::CppTokenKind as K;

    if tokens.first().copied() != Some(K::LeftParen)
        || tokens.last().copied() != Some(K::RightParen)
    {
        return false;
    }

    // The group has to *close* at the last token, not earlier: `(a) + (b)` also starts with `(` and ends with
    // `)`, and it is not one group.
    let mut depth = 0isize;
    for (index, kind) in tokens.iter().enumerate() {
        match kind {
            K::LeftParen => depth += 1,
            K::RightParen => {
                depth -= 1;
                if depth == 0 {
                    return index == tokens.len() - 1;
                }
            }
            _ => {}
        }
    }

    false
}

/// File the declarations and errors one parse found under the files they were written in.
///
/// Every range goes back through [`crate::RenderedUnit::written_span`], which answers with the file the tokens
/// **stand in** and a range in *that* file.
///
/// # Two things are counted as unplaced, and the second one used to be silent
///
/// A range that maps nowhere, and a range whose answer does not land in the file the answer names — the check is
/// [`crate::RenderedUnit::span_lands_in`], and it is the one thing that would have caught
/// `basic_string`'s 93 971-byte class body being filed under a 1.2 KB header. Both halves of a fact are checked
/// (`range` and `name_range`) and they must agree about the file: half in one file and half in another is not "a
/// bit less", it is a fact about nothing (the same rule [`crate::FileSummary::map_into_the_file`] applies per file).
///
/// An error that cannot be placed in any file is counted rather than reported against a text the reader cannot see.
///
/// # Why there is no `skip` set any more
///
/// There used to be one: a file whose brace the fence had given up was filed from a **second parse of its own text**
/// and not from the program's, because the program's had read a text that was no longer the file's. With the fence
/// gone there is one parse of one stream, and every fact from it belongs to the file the fact was written in.
fn file_what_was_found(
    declarations: Vec<crate::DeclFact>,
    tree: &CppSyntaxTree,
    stream: &crate::RenderedUnit,
    files: &mut [(std::path::PathBuf, crate::CookedFile)],
    unplaced: &mut usize,
) {
    // **The switch is read once, by the probe module.** This function runs once per program read, and a `std::env`
    // read here is a lock of the process environment plus an `OsString` built for an answer that cannot change
    // during a run.
    let tracing = crate::probes::attribution();
    let interested = |name: &str| matches!(name, "cout" | "map" | "wcout" | "multimap");
    if tracing {
        eprintln!("[attr] {} declaration(s) to place", declarations.len());
    }
    for mut fact in declarations {
        if tracing && interested(&fact.name) {
            eprintln!(
                "[attr] {} kind {:?} range {}..{}",
                fact.name,
                fact.kind,
                fact.range.start_offset,
                fact.range.end_offset()
            );
        }
        let Some((file, range)) = stream.written_span(fact.range) else {
            if tracing && interested(&fact.name) {
                eprintln!("[attr] {} -> no written span", fact.name);
            }
            *unplaced += 1;
            continue;
        };
        let Some((name_file, name_range)) = stream.written_span(fact.name_range) else {
            *unplaced += 1;
            continue;
        };
        if name_file != file {
            if tracing && interested(&fact.name) {
                eprintln!(
                    "[attr] {} -> the name is in file {name_file}, the declaration in {file}",
                    fact.name
                );
            }
            *unplaced += 1;
            continue;
        }
        if !stream.span_lands_in(file, range) || !stream.span_lands_in(name_file, name_range) {
            *unplaced += 1;
            continue;
        }
        if tracing && interested(&fact.name) {
            eprintln!(
                "[attr] {} -> file {file} {:?}",
                fact.name,
                files.get(file as usize).map(|(path, _)| path.file_name())
            );
        }
        fact.range = range;
        fact.name_range = name_range;
        if let Some((_, cooked)) = files.get_mut(file as usize) {
            cooked.declarations.push(fact);
        }
    }

    // **A stream's parse error is the program's, not a file's — so it is counted, not placed.**
    //
    // The loop that stood here asked `stream.written_span(range)` and pushed the answer into the file the error's
    // *start* landed in. That mapping is by token, and a range that covers tokens from two files is attributed to the
    // first of them with a one-token span, while a range that begins in a gap covers **trivia**: measured on Lua
    // 5.5.0's `ldebug.c`, opened in an editor as "large-scale syntax errors", a program read filed **15** errors
    // against that file at positions inside its doc comments (`** during a signal, under "reasonable"`), none of
    // which is a place the reader can look at.
    //
    // The count is not lost: [`crate::IndexedUnit::errors`] is the stream's own count, and a consumer that wants to
    // say "this program did not parse" has it. What is *not* published is a place for it, because the place the
    // stream gives does not name one.
    let _ = (tree, files, unplaced);
}

/// Give `#include "local.h"` the token the parser gives it: a header name — **the shared implementation lives in
/// [`crate::preprocess::directive::fold_quoted_header_names`]**, because the include walk now reads a header's
/// directives from its tokens rather than from a parse and the two readers must agree about what an include line is.
use crate::preprocess::directive::fold_quoted_header_names;

/// The [`IncludeFact`] for an `#include`, or `None` for every other directive.
///
/// A resolution failure is not an error here: an include that was not found is stored with its spelling and no
/// path, which is what a consumer needs to report "cannot find `widget.h`" rather than to hide it.
/// One `#include` of a file, as a fact — see [`IncludeFact`].
///
/// `range` is **the directive's own line**, not the span the tree gives it: a [`SpannedDirective::range`] runs
/// through the trailing trivia to the next real token, so it swallows the newline, any blank lines and the comment
/// before the following line — and a diagnostic drawn on that range underlines the next line too. Measured from an
/// editor: `#include <asio.hpp>` on line 4 and a URL comment on line 5 were squiggled by one `include-not-found`.
/// [`SpannedDirective::line`] is the same directive without that trivia, and it is what a fact's range should be.
fn include_fact<F: FileProvider>(
    directive: &Directive,
    range: cpp_parser::SourceRange,
    including: &Path,
    resolver: &IncludeResolver<'_, F>,
    interner: &mut PathInterner,
    scanned: Option<&ScannedIncludes>,
) -> Option<IncludeFact> {
    let Directive::Include(include) = directive else {
        return None;
    };

    // A search of the include path is a filesystem search: a scan that already made it is believed, but only for
    // the very same directive.
    let resolved: Option<PathBuf> =
        match scanned.and_then(|scanned| scanned.resolved(range.start_offset, include)) {
            Some(resolved) => resolved,
            None => resolver
                .resolve(include, including, None, interner)
                .resolved()
                .map(|resolved| resolved.path.clone()),
        };

    Some(IncludeFact {
        form: include.form,
        spelling: include.target.to_string(),
        resolved,
        is_next: include.is_next,
        range,
        guard: crate::summary::FactGuard::Unconditional,
    })
}

/// Put a summary on disk, under the path its key names.
///
/// The write is a `.tmp` file followed by a rename, so a crash mid-write leaves the old summary rather than half
/// of a new one — and a half-written summary is worse than none, because a *wrong* entry answers queries that a
/// missing one would have sent to a rebuild.
///
/// `cache_directory` is the directory the summaries live in (`<root>/.cppls` unless a project renamed it); the key
/// names the file inside it, and nothing else about the project's layout is involved.
#[allow(dead_code)]
pub fn write_summary(summary: &FileSummary, cache_directory: &Path) -> std::io::Result<PathBuf> {
    let path = summary.key.path_under(cache_directory);
    let bytes = crate::summary_codec::encode(summary);

    if let Some(directory) = path.parent() {
        std::fs::create_dir_all(directory)?;
    }

    // Unique per write: two files with the same text share a key, and workers writing them at once must not share a
    // temporary — one would rename the other's half-written bytes into place.
    static WRITES: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);
    let temporary = path.with_extension(format!(
        "{}.{}.tmp",
        std::process::id(),
        WRITES.fetch_add(1, std::sync::atomic::Ordering::Relaxed)
    ));
    std::fs::write(&temporary, &bytes)?;
    std::fs::rename(&temporary, &path)?;

    Ok(path)
}

/// Read a summary from disk, or say why it could not be used.
///
/// Every failure is the caller's cue to rebuild: a missing file, a corrupt one, and one written by a different
/// format version are the same decision, and the distinctions are kept because only the last two are worth
/// logging.
#[allow(dead_code)]
pub fn read_summary(path: &Path) -> Result<FileSummary, SummaryReadError> {
    let bytes = std::fs::read(path).map_err(SummaryReadError::Io)?;
    crate::summary_codec::decode(&bytes).map_err(SummaryReadError::Decode)
}

/// Why a stored summary could not be read.
#[derive(Debug)]
pub enum SummaryReadError {
    /// The file could not be read at all.
    Io(std::io::Error),
    /// The bytes are not a summary this build can use.
    Decode(DecodeError),
}

impl std::fmt::Display for SummaryReadError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            SummaryReadError::Io(error) => write!(f, "cannot read the summary: {error}"),
            SummaryReadError::Decode(error) => write!(f, "{error}"),
        }
    }
}

impl std::error::Error for SummaryReadError {}

#[cfg(test)]
mod tests {
    use super::{FileIndexer, include_fact, macro_body_shape, summarize, write_summary};
    use crate::cache::SummaryKey;
    use crate::file::paths::{FileProvider, MemoryFiles, PathInterner};
    use crate::include::IncludeResolver;
    use crate::include::config::CompilerConfig;
    use crate::preprocess::directive::{Directive, IncludeForm};
    use crate::preprocess::macros::MacroTable;
    use crate::summary::{DeclKind, FactGuard, MacroKind};
    use cpp_parser::{CppParser, MacroBody, ParserConfig};
    use std::path::{Path, PathBuf};

    fn key() -> SummaryKey {
        SummaryKey::new(0, 0)
    }

    fn summary(source: &str) -> crate::summary::FileSummary {
        summarize(Path::new("/p/widget.cpp"), source, key())
    }

    #[test]
    fn a_summary_is_read_for_the_compiler_it_was_configured_with() {
        // The dialect has to reach the **parser**, not just the key: `int __int128;` declares a variable called
        // `__int128` when the compiler spells `__int128` as an ordinary name (MSVC), and declares **nothing** when
        // it is a type keyword (GNU) — a name cannot be a declarator if it is a type. A configuration that stopped
        // at the cache key would hash two targets apart and then read both the same way, which is the worst of
        // both.
        //
        // The spelling this test used before was `unsigned __int128 x;`, and it stopped distinguishing the two
        // dialects when the specifier sequence learned to let a name join a type that is already there
        //: `__int128 x` is a type and a declarator under *both* dialects now, which
        // is the better reading of both. What the dialect decides is whether the token **can** be a declarator, and
        // that is what this spelling asks.
        let files = MemoryFiles::new();
        let names = |dialect: cpp_parser::Dialect| {
            let config = CompilerConfig::default().with_dialect(dialect);
            let summary = FileIndexer::new(&files, &config).index(
                Path::new("/p/a.cpp"),
                "int __int128;\n",
                key(),
            );
            summary
                .declarations
                .iter()
                .map(|fact| fact.name.to_string())
                .collect::<Vec<_>>()
        };

        assert_eq!(
            names(cpp_parser::Dialect::Gnu),
            Vec::<String>::new(),
            "under GNU `__int128` is a type, so `int __int128;` has no declarator"
        );
        assert_eq!(
            names(cpp_parser::Dialect::Msvc),
            vec!["__int128".to_string()],
            "and under MSVC the same text declares a variable called `__int128`"
        );
    }

    /// Every region's branches, as `kind condition body-start..body-end`, for a short assertion.
    ///
    /// The regions of a summary used to be spans and nothing else, and a span of a *condition* is not a
    /// question any layer could answer. This is the shape that replaced it: what each branch asks, and which
    /// text it guards.
    fn region_shapes(source: &str) -> Vec<Vec<String>> {
        let summary = summary(source);

        summary
            .guards
            .conditionals
            .iter()
            .map(|conditional| {
                conditional
                    .branches
                    .iter()
                    .map(|branch| {
                        format!(
                            "{:?} {} {}..{}",
                            branch.kind,
                            branch.condition.as_deref().unwrap_or("-"),
                            branch.body.start_offset,
                            branch.body.end_offset()
                        )
                    })
                    .collect()
            })
            .collect()
    }

    #[test]
    fn a_summary_stores_what_each_conditional_asks() {
        // The three spellings a condition comes in, and the one that has none. `#ifdef`/`#ifndef` store the
        // *name*, `#if` stores the expression's text — read back with the lexer the evaluator will use — and
        // `#else` stores nothing, which is not the same as storing an empty expression.
        let shapes = region_shapes(
            "#if defined(_WIN32)\n#include <a.h>\n#elif __cplusplus >= 201703L\n#include <b.h>\n#else\n#include <c.h>\n#endif\n",
        );

        assert_eq!(shapes.len(), 1, "one conditional, three branches");
        let branches = &shapes[0];
        assert_eq!(branches.len(), 3);
        assert!(
            // **The source's spelling, not a space between every token.** `defined(_WIN32)` is what the file
            // writes and what a configuration carries; the space-joined form was an artefact of how the text used
            // to be rebuilt, and rebuilding it faithfully is what keeps `__cplusplus >= 201703L` from becoming
            // `__cplusplus > = 201703L` when the `>`-family arrives in pieces. See `conditional_branch`.
            branches[0].starts_with("If defined(_WIN32)"),
            "the expression's tokens, spelled as the source wrote them: {}",
            branches[0]
        );
        assert!(
            branches[1].starts_with("Elif __cplusplus >= 201703L"),
            "a version test is stored as the text a value can be compared against: {}",
            branches[1]
        );
        assert!(
            branches[2].starts_with("Else -"),
            "`#else` asks nothing: {}",
            branches[2]
        );

        // And the bodies are where the reader would put them: each branch's text is between its own directive
        // and the *start of the next one*, which is where the `#endif` is — the directive itself is not body.
        let source = "#ifdef A\n#include <a.h>\n#endif\n";
        let shapes = region_shapes(source);
        assert_eq!(
            shapes[0][0],
            format!(
                "Ifdef A {}..{}",
                source.find("#ifdef").expect("the directive") + "#ifdef A\n".len(),
                source.find("#endif").expect("the #endif")
            ),
            "the `#ifdef` branch guards everything between its directive and the `#endif`"
        );
    }

    #[test]
    fn a_regions_parent_is_the_conditional_it_is_written_inside() {
        // A nested region's condition lies inside its parent's body, and so does the text of a sibling branch —
        // which is why the nesting is stored rather than derived from the spans.
        let nested = summary("#ifdef A\n#ifdef B\nint x;\n#endif\n#endif\n");
        let parents: Vec<Option<u32>> = nested
            .guards
            .conditionals
            .iter()
            .map(|conditional| conditional.parent)
            .collect();
        assert_eq!(parents, [None, Some(0)]);

        // …and an `#elif` does not open a second region: the region *is* the conditional, and its branches are
        // the chain written inside it.
        let chained =
            summary("#ifdef A\nint a;\n#elif defined(B)\nint b;\n#else\nint c;\n#endif\n");
        assert_eq!(chained.guards.conditionals.len(), 1);
        assert_eq!(chained.guards.conditionals[0].branches.len(), 3);
        assert!(chained.guards.conditionals[0].exhaustive());
    }

    #[test]
    fn the_code_a_position_is_in_is_found_by_walking_outwards() {
        // `conditions_at` is what a fact's guard index cannot say on its own: a fact records the *innermost*
        // region, and whether the code is compiled is a question about every region around it.
        let source = "#ifdef A\n#ifdef B\nint x;\n#endif\n#endif\n";
        let summary = summary(source);
        let x = source.find("int x;").expect("the declaration");

        let chain = summary.guards.conditions_at(x);
        assert_eq!(
            chain.iter().map(|at| at.region).collect::<Vec<_>>(),
            [1, 0],
            "innermost first"
        );
        assert!(
            chain.iter().all(|at| at.condition_at < x),
            "and each condition is evaluated at its *own* offset, which is above the code: {chain:?}"
        );

        // Code outside every conditional is in no region at all — the common case, and the cheap one.
        let source = "int x;\n#ifdef A\nint y;\n#endif\n";
        assert!(
            summary
                .guards
                .conditions_at(source.find("int x;").expect("the declaration"))
                .is_empty()
        );
    }

    #[test]
    fn a_position_is_looked_up_in_the_branch_it_sits_in() {
        // The branch in force is what decides whether the code is compiled, and it is a question about the
        // position — `#else` is not "the whole region", it is one branch of it.
        let source = "#ifdef A\nint taken;\n#else\nint not_taken;\n#endif\n";
        let summary = summary(source);
        let region = summary.guards.conditionals.first().expect("one region");

        let first = source.find("int taken").expect("the first branch");
        let second = source.find("int not_taken").expect("the second branch");
        assert_eq!(region.branch_at(first), Some(0));
        assert_eq!(region.branch_at(second), Some(1));
    }

    #[test]
    fn the_chain_a_guard_names_is_the_chain_the_position_is_in() {
        // Two ways to the same answer: from the guard a fact carries (each region names its parent, so this is a
        // walk outwards), and from the position (a search over every region's span). They must agree — the guard
        // is the innermost region the sweep found, and the spans are that same sweep's arithmetic. Where they do
        // not, the file's directives do not balance and the structure is two readings of one broken file; the
        // guard is the one the rest of the index is consistent with.
        for source in [
            "#ifdef A\nint x;\n#endif\n",
            "#ifdef A\n#ifdef B\nint x;\n#endif\n#endif\n",
            "#ifdef A\nint a;\n#elif defined(B)\nint b;\n#else\nint c;\n#endif\n",
            "#ifndef GUARD\n#define GUARD\n#ifdef A\nint x;\n#endif\n#endif\n",
            "int early;\n#if defined(A) && defined(B)\n#ifdef C\nint x;\n#else\nint y;\n#endif\n#endif\n",
        ] {
            let summary = summary(source);

            for (region, conditional) in summary.guards.conditionals.iter().enumerate() {
                for branch in &conditional.branches {
                    // Anywhere inside the branch's body is a position whose guard names this region — unless a
                    // *nested* region is there, which is what the chain has to account for either way.
                    if branch.body.length == 0 {
                        continue;
                    }

                    let at = branch.body.start_offset;
                    assert_eq!(
                        summary.guards.conditions_at(at),
                        summary.guards.conditions_of(region as u32),
                        "{source:?} at {at} (region {region})"
                    );
                }
            }
        }
    }

    #[test]
    fn a_definition_carries_a_value_exactly_when_a_condition_could_read_one() {
        // `#if NAME` expands the name and reads the result as a number, and the evaluator accepts **one integer
        // literal** — so the fact stores a value in exactly that case and nothing else. A name defined to a name,
        // to an expression, to nothing, or as a function-like macro is `Unknown` to a condition, and a spelling no
        // evaluator can use would only make the cache bigger.
        let value_of = |source: &str, name: &str| {
            summary(source)
                .macros
                .iter()
                .find(|fact| fact.name == name)
                .and_then(|fact| fact.value.clone())
        };

        assert_eq!(value_of("#define ABI 1\n", "ABI").as_deref(), Some("1"));
        assert_eq!(
            value_of("#define WIDE 0x10UL\n", "WIDE").as_deref(),
            Some("0x10UL"),
            "the spelling is kept as written: the evaluator is what reads it"
        );
        assert_eq!(value_of("#define NAME other\n", "NAME"), None);
        assert_eq!(value_of("#define EXPR 1 + 2\n", "EXPR"), None);
        assert_eq!(value_of("#define EMPTY\n", "EMPTY"), None);
        assert_eq!(value_of("#define CALL(x) x\n", "CALL"), None);
        assert_eq!(
            value_of("#undef GONE\n", "GONE"),
            None,
            "an `#undef` says the name stops being a macro, which is all it says"
        );
    }

    /// The facts about `name`, with their guards and the settling flag, for a short assertion.
    fn macro_facts(source: &str, name: &str) -> Vec<(crate::summary::MacroKind, FactGuard, bool)> {
        summary(source)
            .macros
            .iter()
            .filter(|fact| fact.name == name)
            .map(|fact| (fact.kind, fact.guard, fact.settles_the_name))
            .collect()
    }

    #[test]
    fn a_define_inside_ifndef_settles_the_name_whatever_the_branch() {
        // The idiom the whole flag exists for, and the shape the system headers define most macros in:
        // `#ifndef NAME / #define NAME`. Taken → defined here; not taken → it was defined already. Either way the
        // name is a macro, so a *use* after this block is a use and not a "maybe".
        //
        // A declaration before the conditional is what keeps it from being the **file's own guard** — which is a
        // separate rule that would make the fact `Unconditional` instead (see the test after this one).
        assert_eq!(
            macro_facts("int early;\n#ifndef NAME\n#define NAME 1\n#endif\n", "NAME"),
            [(MacroKind::Definition, FactGuard::Region(0), true)]
        );
    }

    #[test]
    fn the_files_own_guard_is_not_a_condition_and_neither_is_a_define_inside_it() {
        // `#ifndef WIDGET_H / #define WIDGET_H` wrapping the file is a guard, so its facts are unconditional
        // already — and a `#ifndef NAME` nested inside one inherits that: reaching the file at all is what the
        // guard means, which is the same rule the de-guard step applies to declarations and includes.
        assert_eq!(
            macro_facts(
                "#ifndef WIDGET_H\n#define WIDGET_H\n#ifndef NAME\n#define NAME 1\n#endif\n#endif\n",
                "NAME"
            ),
            [(MacroKind::Definition, FactGuard::Region(1), true)]
        );
        assert_eq!(
            macro_facts("#ifndef WIDGET_H\n#define WIDGET_H\n#endif\n", "WIDGET_H"),
            [(MacroKind::Definition, FactGuard::Unconditional, false)]
        );
    }

    #[test]
    fn a_region_whose_every_branch_agrees_settles_the_name() {
        // The general case behind the idiom: whichever branch ran, it did the same thing to the name. The two
        // definitions may differ in what they define it *as* — that is the question the flag deliberately does not
        // answer, and `macro_definition` therefore still ignores it.
        assert_eq!(
            macro_facts(
                "int early;\n#if defined(A)\n#define NAME 1\n#else\n#define NAME 2\n#endif\n",
                "NAME"
            ),
            [
                (MacroKind::Definition, FactGuard::Region(0), true),
                (MacroKind::Definition, FactGuard::Region(0), true)
            ]
        );

        // `#ifdef NAME / #undef NAME` is the mirror: after it the name is certainly not a macro.
        assert_eq!(
            macro_facts("int early;\n#ifdef NAME\n#undef NAME\n#endif\n", "NAME"),
            [(MacroKind::Undefinition, FactGuard::Region(0), true)]
        );
    }

    #[test]
    fn a_region_that_does_not_settle_the_name_marks_nothing() {
        // The four shapes that must stay false, because a rule that over-claims is worse than no rule at all: a
        // single branch that may not be taken; branches that disagree; a branch whose last word on the name is the
        // opposite of what it started with; and a `#define` in a branch that the condition does not name.
        for source in [
            // No `#else`: "nothing ran" is a possibility, and then the name may not be a macro.
            "int early;\n#if defined(A)\n#define NAME 1\n#endif\n",
            // Branches that disagree about the name.
            "int early;\n#if defined(A)\n#define NAME 1\n#else\n#undef NAME\n#endif\n",
            // The branch's *last* word is `#undef`, so the branch leaves the name undefined.
            "int early;\n#ifndef NAME\n#define NAME 1\n#undef NAME\n#endif\n",
            // The condition is not about this name, so nothing about it is settled.
            "int early;\n#ifndef OTHER\n#define NAME 1\n#endif\n",
            // A name defined in only one of two exhaustive branches: the other one leaves it as it found it.
            "int early;\n#if defined(A)\n#define NAME 1\n#else\n#define OTHER 2\n#endif\n",
        ] {
            let facts = macro_facts(source, "NAME");
            assert!(
                facts.iter().all(|(_, _, settles)| !settles),
                "{source:?} must settle nothing, got {facts:?}"
            );
        }
    }

    #[test]
    fn a_settling_region_inside_a_plain_conditional_settles_nothing() {
        // The chain rule, and the case it exists for: if `A` is false the inner `#ifndef NAME` never runs, so
        // nothing about the name is certain — the outer region does not settle it either.
        assert_eq!(
            macro_facts(
                "int early;\n#if defined(A)\n#ifndef NAME\n#define NAME 1\n#endif\n#endif\n",
                "NAME"
            ),
            [(MacroKind::Definition, FactGuard::Region(1), false)]
        );
    }

    #[test]
    fn a_settling_region_reached_through_an_if_defined_settles_the_name() {
        // The shape the system headers actually use: `#if !defined(NAME)` written out instead of `#ifndef NAME`,
        // and wrapped in parentheses for good measure. Recognised as the same claim, because it *is* the same
        // claim — the condition is about the very name the body writes.
        for condition in ["!defined(NAME)", "!defined NAME", "(!defined(NAME))"] {
            let source = format!("int early;\n#if {condition}\n#define NAME 1\n#endif\n");
            assert_eq!(
                macro_facts(&source, "NAME"),
                [(MacroKind::Definition, FactGuard::Region(0), true)],
                "{condition} should settle the name"
            );
        }
    }

    #[test]
    fn a_file_whose_conditionals_do_not_balance_settles_nothing() {
        // The safety net, and the reason it exists: the rule reads a *nesting*, and the nesting comes from the
        // directives the parser found. A file with syntax errors can lose one — measured, `winnt.h` loses eight
        // `#endif`s and 417 errors is what it costs — and a parent chain that is wrong in the shorter direction
        // would claim a name is settled when an enclosing `#if` says it may not be. So an unbalanced file gets no
        // claims at all, in either direction.
        for source in [
            // A region never closed: the `#ifndef NAME` may be inside something that is not taken.
            "int early;\n#if defined(A)\n#ifndef NAME\n#define NAME 1\n#endif\n",
            // An `#endif` that closes nothing: an opener is missing, and the depth after it is wrong.
            "int early;\n#endif\n#ifndef NAME\n#define NAME 1\n#endif\n",
        ] {
            let facts = macro_facts(source, "NAME");
            assert!(
                facts.iter().all(|(_, _, settles)| !settles),
                "{source:?} must settle nothing, got {facts:?}"
            );
        }
    }

    #[test]
    fn a_file_with_declarations_and_macros_summarizes_both() {
        let summary = summary(
            "#define MY_API\n#define MAX(a, b) ((a) > (b) ? (a) : (b))\nstruct Widget { int size; };\n",
        );

        assert_eq!(summary.declarations.len(), 2, "the class and its member");
        assert_eq!(summary.macros.len(), 2, "both macros");

        let api = summary
            .macros
            .iter()
            .find(|fact| fact.name == "MY_API")
            .expect("the object-like macro is a fact");
        assert!(!api.function_like);
        assert_eq!(api.body, MacroBody::Unknown, "an empty body has no shape");

        let max = summary
            .macros
            .iter()
            .find(|fact| fact.name == "MAX")
            .expect("the function-like macro is a fact");
        assert!(max.function_like);
        assert_eq!(
            max.body,
            MacroBody::Expression,
            "the body is one parenthesised group"
        );
    }

    #[test]
    fn a_declaration_inside_the_files_own_guard_is_unconditional() {
        // The rule that makes a header's contents visible at all: `#ifndef H` … `#endif` around the whole file is
        // not a condition anybody has to decide, because *including the file* is what defines `H`. Measured on the
        // closure of `<string>`, without this rule every cross-file answer about the standard library is
        // `ConditionalCompilation` — the headers guard their bodies, so every `#include` inside one is "guarded".
        let summary = summary(
            "#ifndef H\n#define H\nstruct Widget { int size; };\n#include \"other.h\"\n#endif\n",
        );

        let widget = summary
            .declarations
            .iter()
            .find(|fact| fact.name == "Widget")
            .expect("the guarded declaration is a fact");
        assert_eq!(
            widget.guard,
            FactGuard::Unconditional,
            "the file's own guard is entered by including the file at all"
        );

        let include = summary
            .includes
            .iter()
            .find(|fact| fact.spelling == "other.h")
            .expect("the include is a fact");
        assert_eq!(
            include.guard,
            FactGuard::Unconditional,
            "and so is an `#include` written inside it"
        );

        assert_eq!(
            summary.guards.regions.len(),
            1,
            "the region is still recorded: the `#if` is a fact about the text either way"
        );
    }

    #[test]
    fn a_conditional_that_is_not_the_files_guard_still_guards() {
        // What the rule must not swallow: `#if defined(A)` is a real condition, and a fact inside it is still
        // `Unknown` to a consumer that cannot evaluate it.
        let summary = summary("#if defined(A)\nint inside;\n#endif\n");

        let fact = summary
            .declarations
            .iter()
            .find(|fact| fact.name == "inside")
            .expect("the declaration is a fact");
        assert_eq!(fact.guard, FactGuard::Region(0));
    }

    #[test]
    fn a_header_that_declares_something_before_its_guard_is_not_guarded_by_it() {
        // `detect_guard` refuses a guard that does not wrap the whole file, and the rule follows it rather than
        // making up its own answer: the `#ifndef` here is an ordinary conditional and stays one.
        let summary = summary("int early;\n#ifndef H\n#define H\nint inside;\n#endif\n");

        let early = summary
            .declarations
            .iter()
            .find(|fact| fact.name == "early")
            .expect("the declaration before the guard is a fact");
        assert_eq!(
            early.guard,
            FactGuard::Unconditional,
            "it is outside every region, which is a different answer from the guard's"
        );

        let inside = summary
            .declarations
            .iter()
            .find(|fact| fact.name == "inside")
            .expect("the declaration inside is a fact");
        assert_eq!(
            inside.guard,
            FactGuard::Region(0),
            "a guard that does not wrap the file does not de-guard what it does contain"
        );
    }

    #[test]
    fn a_declaration_in_a_conditional_keeps_its_region_through_the_builder() {
        let summary = summary("#if defined(A)\nint inside;\n#endif\n");

        assert_eq!(summary.guards.regions.len(), 1);
        let fact = summary
            .declarations
            .iter()
            .find(|fact| fact.name == "inside")
            .expect("the guarded declaration is a fact");
        assert_eq!(fact.guard, FactGuard::Region(0));
    }

    #[test]
    fn an_include_that_cannot_be_resolved_keeps_its_spelling() {
        let summary = summary("#include <vector>\n#include \"local.h\"\n");

        assert_eq!(summary.includes.len(), 2);

        let vector = &summary.includes[0];
        assert_eq!(vector.form, IncludeForm::Angle);
        assert_eq!(vector.spelling, "vector");
        assert_eq!(
            vector.resolved, None,
            "with nothing to search, the include is unresolved rather than dropped"
        );

        assert_eq!(summary.includes[1].form, IncludeForm::Quote);
        assert_eq!(summary.includes[1].spelling, "local.h");
    }

    #[test]
    fn an_include_resolves_against_the_provider() {
        let files = MemoryFiles::new()
            .with_file("/p/local.h", "int x;\n")
            .with_file("/usr/include/vector", "// the real one\n");

        // An *angle* include searches the configured paths and not the including file's directory, so the
        // configuration is what makes it resolvable — a distinction worth a test, because a resolver that
        // searched the local directory for `<vector>` would find a project's own file of that name and shadow
        // the standard header.
        let mut config = CompilerConfig::default();
        config.include_paths = vec![crate::include::config::IncludePath::system("/usr/include")];

        let indexer = FileIndexer::new(&files, &config);
        let summary = indexer.index(
            Path::new("/p/widget.cpp"),
            "#include <vector>\n#include \"local.h\"\n",
            key(),
        );

        let vector = summary
            .includes
            .iter()
            .find(|fact| fact.spelling == "vector")
            .expect("the angle include is a fact");
        assert_eq!(
            vector.resolved.as_deref(),
            Some(Path::new("/usr/include/vector")),
            "an angle include searched the configured path"
        );

        let local = summary
            .includes
            .iter()
            .find(|fact| fact.spelling == "local.h")
            .expect("the quoted include is a fact");
        assert_eq!(
            local.resolved.as_deref(),
            Some(Path::new("/p/local.h")),
            "a quoted include looks beside the including file first"
        );
    }

    #[test]
    fn every_summary_survives_being_written_and_read_back() {
        let directory = std::env::temp_dir().join("cppls-summary-round-trip");
        let _ = std::fs::remove_dir_all(&directory);

        let summary = summary(
            "#define MY_API\n#if defined(A)\nstruct Widget { int size; };\n#endif\n#include <vector>\n",
        );
        let written = write_summary(&summary, &directory).expect("the write must succeed");

        assert!(
            written.starts_with(&directory),
            "the summary lands under the project root: {written:?}"
        );

        let read = super::read_summary(&written).expect("what was written must be readable");
        assert_eq!(read, summary);

        let _ = std::fs::remove_dir_all(&directory);
    }

    #[test]
    fn the_macro_body_classifier_reads_each_shape() {
        let cases = [
            ("#define A __declspec(dllexport)", MacroBody::Specifier),
            ("#define A extern \"C\"", MacroBody::Specifier),
            ("#define A do { } while (false)", MacroBody::Statement),
            ("#define A if (x) { }", MacroBody::Statement),
            ("#define A return", MacroBody::Statement),
            ("#define A ((a) > (b) ? (a) : (b))", MacroBody::Expression),
            ("#define A (a)", MacroBody::Expression),
            ("#define A int", MacroBody::Type),
            ("#define A unsigned long", MacroBody::Type),
            ("#define A { }", MacroBody::Block),
            ("#define A", MacroBody::Unknown),
            ("#define A something_else + 1", MacroBody::Unknown),
        ];

        for (source, expected) in cases {
            let tree = CppParser::parse(source, ParserConfig::default());
            let preprocessing = crate::preprocess::preprocess(source, tree.get_tokens());

            let Directive::Define(define) = &preprocessing.directives[0].directive else {
                panic!("{source:?} must be a define");
            };
            let definition = define.macro_def.as_ref().expect("a readable definition");

            assert_eq!(
                macro_body_shape(definition),
                expected,
                "{source:?} should be {expected:?}"
            );
        }
    }

    #[test]
    fn a_body_that_is_not_one_parenthesised_group_is_not_an_expression() {
        // `(a) + (b)` is a sum: it starts with `(` and ends with `)` and the group closes before the end. Calling
        // it an expression would be right in this case and wrong for a statement that happens to be written that
        // way, so the answer is `Unknown` — which still rules out the call reading.
        let tree = CppParser::parse("#define A (a) + (b)", ParserConfig::default());
        let preprocessing = crate::preprocess::preprocess("#define A (a) + (b)", tree.get_tokens());

        let Directive::Define(define) = &preprocessing.directives[0].directive else {
            panic!("must be a define");
        };
        let definition = define.macro_def.as_ref().expect("a readable definition");

        assert_eq!(macro_body_shape(definition), MacroBody::Unknown);
    }

    #[test]
    fn an_unresolved_include_does_not_stop_the_other_facts() {
        let tree = CppParser::parse(
            "#include <nonexistent_xyz>\nstruct W { int a; };\n",
            ParserConfig::default(),
        );
        let preprocessing = crate::preprocess::preprocess(
            "#include <nonexistent_xyz>\nstruct W { int a; };\n",
            tree.get_tokens(),
        );

        let files = MemoryFiles::new();
        let config = CompilerConfig::default();
        let mut interner = PathInterner::new(cfg!(windows));
        let resolver = IncludeResolver::new(&files, &config);

        let facts: Vec<_> = preprocessing
            .directives
            .iter()
            .filter_map(|spanned| {
                include_fact(
                    &spanned.directive,
                    spanned.line,
                    Path::new("/p"),
                    &resolver,
                    &mut interner,
                    None,
                )
            })
            .collect();

        assert_eq!(facts.len(), 1);
        assert_eq!(facts[0].spelling, "nonexistent_xyz");
        assert_eq!(facts[0].resolved, None);
    }

    #[test]
    fn a_macro_fact_points_at_the_name_not_the_directive() {
        let summary = summary("  #define   MY_API   int\n");

        let fact = summary
            .macros
            .iter()
            .find(|fact| fact.name == "MY_API")
            .expect("the macro is a fact");

        // The name is what a rename edits and what a "go to definition" puts the cursor on.
        let text = "  #define   MY_API   int\n";
        assert_eq!(
            &text[fact.range.start_offset..fact.range.end_offset()],
            "MY_API"
        );
    }

    #[test]
    fn a_summary_carries_no_resolved_conclusions() {
        // The first invariant, asserted rather than assumed: a summary holds names as
        // written and nothing that would have to be recomputed when a header changes.
        let summary = summary("namespace ns { struct Widget { int member; }; }\n");

        let widget = summary
            .declarations
            .iter()
            .find(|fact| fact.name == "Widget")
            .expect("the class is a fact");

        assert_eq!(widget.kind, DeclKind::Type);
        assert_eq!(
            widget.scope.as_deref(),
            Some("ns"),
            "the scope is the spelling the file used, not a resolved identity"
        );
        assert_eq!(widget.qualified_name(), "ns::Widget");
    }

    /// A provider with one file, for the resolution test above.
    struct OneFile(PathBuf, String);

    impl FileProvider for OneFile {
        fn read(&self, path: &Path) -> Option<String> {
            (path == self.0).then(|| self.1.clone())
        }

        fn exists(&self, path: &Path) -> bool {
            path == self.0
        }
    }

    #[test]
    fn a_provider_that_has_one_file_still_answers_for_it() {
        let files = OneFile(PathBuf::from("/p/only.h"), "int x;\n".to_string());
        let table = MacroTable::new();
        let _ = table;

        assert_eq!(
            files.read(Path::new("/p/only.h")).as_deref(),
            Some("int x;\n")
        );
        assert_eq!(files.read(Path::new("/p/other.h")), None);
    }
}