cpp_code_analysis 0.3.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
//! **One walk of a translation unit, read from by every file in it.**
//!
//! The per-file reading — "walk *this* file's include closure and hand it the result" — costs one full walk per
//! file, and the census put a number on it: 255 files of the Windows SDK corpus, 2 489 142 macro entries
//! materialised, 17 618 794 conditional facts evaluated, 147 s of a 174 s run. `TranslationUnit` is the
//! timeline that replaces it: the unit is walked **once**, and a file's environment is read out of that walk.
//!
//! # What these tests are for
//!
//! A cheaper walk is worthless if it answers differently, and "differently" here is not a diagnostic — it is a
//! macro that is in force in one reading and not in the other, which shows up much later as a parse that reads
//! something else. So the central test compares the two readings **question by question**: for every name and
//! every offset that appears in the file, `kind_of`, `body_text_of` and `parameters_of` must agree with what the
//! per-file closure walk built.
//!
//! The two readings *should* differ in exactly one place, and it is an improvement rather than a regression: the
//! inherited state of a header. The per-file walk could only approximate it from one includer (the probe's
//! BFS-chosen one), while the timeline has the real translation unit state at the `#include`. The test asserts the
//! agreement on a file whose closure says everything the prefix would, so the approximation is not in play; the
//! census is where the difference is measured.

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

use cpp_code_analysis::graph::Marked;
use cpp_code_analysis::{
    CompilerConfig, FileIndexer, FileSummary, MacroBindings, MacroDefinitions, MemoryFiles,
    SummaryKey, TranslationUnit,
};
use cpp_parser::MacroFacts;

/// A file set in memory, indexed once, with the two ways of asking for a file's environment.
struct Unit {
    summaries: HashMap<PathBuf, FileSummary>,
    sources: HashMap<PathBuf, String>,
    /// The provider the set came from — kept because the cache validates against **files**, not against a
    /// summary map, and a test that hands it one must hand it the same texts the walk read.
    files: MemoryFiles,
    seed: Marked,
}

impl Unit {
    fn new(files: &[(&str, &str)]) -> Self {
        let mut provider = MemoryFiles::new();
        for (path, text) in files {
            provider.insert(path, *text);
        }

        // Every directory of the set is on the search path, so `#include "x.h"` resolves the way the probe's
        // corpus does — the arrangement is the caller's, and this test only needs one that resolves.
        let mut config = CompilerConfig::default();
        for (path, _) in files {
            if let Some(parent) = Path::new(path).parent() {
                config = config.with_include_path(parent.to_path_buf());
            }
        }

        let indexer = FileIndexer::new(&provider, &config);
        let key = SummaryKey::new(0, 0);
        let mut summaries = HashMap::new();
        let mut sources = HashMap::new();
        for (path, text) in files {
            let path = PathBuf::from(path);
            summaries.insert(path.clone(), indexer.index(&path, text, key));
            sources.insert(path, (*text).to_string());
        }

        Unit {
            summaries,
            sources,
            files: provider,
            // A seed with the two names every corpus asks about, so a `#ifdef` in the fixtures is answerable.
            seed: {
                let mut marked = Marked::default();
                marked.define_on_the_command_line("__cplusplus", Some("202002L"));
                marked.define_on_the_command_line("_WIN32", Some("1"));
                marked
            },
        }
    }

    fn look_up(&self, wanted: &Path) -> Option<(&FileSummary, &str)> {
        Some((
            self.summaries.get(wanted)?,
            self.sources.get(wanted).map(String::as_str).unwrap_or(""),
        ))
    }

    /// The per-file reading: walk this file's own include closure.
    fn per_file(
        &self,
        path: &str,
        definitions: &mut MacroDefinitions,
    ) -> cpp_parser::MacroEnvironment {
        let path = PathBuf::from(path);
        let summary = self.summaries.get(&path).expect("indexed");
        let evidence = cpp_code_analysis::macros_from_the_closure_with_bodies(
            summary,
            |wanted| self.look_up(wanted),
            &self.seed,
            definitions,
        );

        cpp_parser::MacroEnvironment::from_included_macros(evidence.macros)
            .with_bodies_in_force(evidence.conditional_bodies)
    }

    /// The one-walk reading: the unit's timeline, and the file's view of it.
    fn timeline_of(&self, root: &str, definitions: &mut MacroDefinitions) -> TranslationUnit {
        let root = PathBuf::from(root);
        TranslationUnit::walk(
            self.summaries.get(&root).expect("indexed"),
            |wanted| self.look_up(wanted),
            &self.seed,
            definitions,
            false,
            &cpp_code_analysis::WalkCache::new(),
        )
    }
}

/// Every question the parser can ask of an environment, asked of both readings.
///
/// `&dyn MacroFacts` rather than either of the two types, because comparing the readings is the whole point: the
/// per-file walk answers them out of a materialised `MacroEnvironment` and the unit answers them out of a
/// [`cpp_code_analysis::MacroView`], and a test that had to name one of them could not ask both the same question.
fn answers(
    environment: &dyn cpp_parser::MacroFacts,
    name: &str,
    offset: usize,
) -> (
    Option<String>,
    Option<String>,
    Option<String>,
    Option<String>,
) {
    let kind = environment
        .kind_of(name, offset)
        .map(|kind| format!("{kind:?}"));
    (
        kind,
        environment.body_text_of(name, offset).map(str::to_string),
        environment
            .parameters_of(name, offset)
            .map(|list| list.to_string()),
        environment.body_text_in_force(name).map(str::to_string),
    )
}

/// **The one-walk reading answers everything the per-file walk answered — and one thing it cannot.**
///
/// The fixture is the shape the corpus is made of: a header that defines macros **conditionally**, a header that
/// includes it and defines more, a source file that includes both, and a header that names something neither of
/// them defines.
///
/// # The two readings, and the one place they must differ
///
/// ```text
/// per_file   a MacroEnvironment materialised out of the closure: every `#define` the includes write, stamped with
///            the offset of the `#include` that brings it in (`IncludedMacro::from_offset`)
/// timeline   the walk, which evaluated every condition on its way through — the same facts, plus the branch taken
/// ```
///
/// A `#define` **inside a condition** is the difference, and it is structural rather than a shortcut: deciding
/// `#ifdef __cplusplus` needs the state of the unit at that point, so a caller with only a closure cannot stamp the
/// definition at an offset. It goes into the environment's read-only "body in force" channel instead
/// ([`MacroFacts::body_text_in_force`]), which a rule may *read* and must not take as "this name is a macro here".
///
/// So the assertion is the strongest one that is true: wherever the fallback answers, the two agree exactly; the
/// in-force channel agrees at every offset; and a difference is only allowed for a name whose body the fallback
/// carries in force — that is, one whose definition the fallback could not place.
#[test]
fn the_timeline_answers_what_the_per_file_walk_answered() {
    let files = [
        (
            "/p/config.h",
            "#ifndef _CONFIG_H_\n\
             #define _CONFIG_H_\n\
             #ifdef __cplusplus\n\
             #define SA(id) id\n\
             #else\n\
             #define SA(id) SA_##id\n\
             #endif\n\
             #define REPEATABLE [repeatable]\n\
             #endif\n",
        ),
        (
            "/p/api.h",
            "#include \"config.h\"\n\
             #define API_CALL __cdecl\n\
             #if _WIN32\n\
             #define WINDOWS 1\n\
             #endif\n\
             API_CALL void f(SA(int) value);\n",
        ),
        (
            "/p/main.cpp",
            "#include \"api.h\"\n\
             int before = API_CALL;\n\
             WINDOWS\n",
        ),
    ];

    let unit = Unit::new(&files);
    let mut definitions = MacroDefinitions::default();
    let per_file = unit.per_file("/p/api.h", &mut definitions);
    let timeline = unit.timeline_of("/p/main.cpp", &mut definitions);
    let view = timeline
        .environment_of(Path::new("/p/api.h"))
        .expect("the unit reaches api.h");

    // Every name the unit mentions, at every offset the file has — the question set is the file's own length, so
    // a difference cannot hide in an offset the test forgot to ask about.
    let source = unit.sources.get(Path::new("/p/api.h")).expect("read");
    let names = [
        "SA",
        "REPEATABLE",
        "API_CALL",
        "WINDOWS",
        "_CONFIG_H_",
        "f",
        "value",
    ];
    let mut the_timeline_knew_more = 0usize;
    for name in names {
        for offset in (0..source.len()).step_by(7) {
            let materialised = answers(&per_file, name, offset);
            let walked = answers(&view, name, offset);

            let positioned =
                |answer: &(
                    Option<String>,
                    Option<String>,
                    Option<String>,
                    Option<String>,
                )| { (answer.0.clone(), answer.1.clone(), answer.2.clone()) };

            // **The positional answer, wherever the fallback has one.** This is the comparison the test exists
            // for: the name at that offset, its body, its parameter list.
            if materialised.0.is_some() || materialised.1.is_some() || materialised.2.is_some() {
                assert_eq!(
                    positioned(&walked),
                    positioned(&materialised),
                    "`{name}` at offset {offset} of api.h: the fallback answers this position and the timeline \
                     does not answer it the same way"
                );
            } else if walked.0.is_some() || walked.1.is_some() || walked.2.is_some() {
                // **…and where it has none, the timeline may — but only for a body the fallback carries in force.**
                // A `#define` inside a condition cannot be stamped at an offset without the unit's state, so the
                // fallback files it under "in force" and reads it without claiming it is a macro here; the walk
                // decided the branch, so it can say. See [`MacroFacts::body_text_in_force`].
                assert!(
                    per_file.body_text_in_force(name).is_some(),
                    "`{name}` at offset {offset} of api.h: the timeline answered {:?}, the fallback {:?} — and the \
                     fallback does not even carry the name's body in force, so this is not a conditional it could \
                     not place",
                    positioned(&walked),
                    positioned(&materialised),
                );
                the_timeline_knew_more += 1;
            }

            // **The in-force channel.** The timeline may carry more names than the fallback here (every definition
            // it met inside a conditional region is also a body in force), and nothing may disagree.
            if let Some(body) = materialised.3.as_deref() {
                assert_eq!(
                    walked.3.as_deref(),
                    Some(body),
                    "`{name}` at offset {offset} of api.h: the fallback has a body in force and the timeline has \
                     another"
                );
            }
        }
    }
    assert!(
        the_timeline_knew_more > 0,
        "the allowance has to be used by this fixture, or the test is not asserting anything about it"
    );

    // …and the precondition of the whole comparison, asserted rather than assumed: both readings really do know
    // the names that come **from the include**, so "they agree" is not "they are both empty".
    assert_eq!(
        per_file.body_text_of("API_CALL", source.len()),
        None,
        "the per-file walk carries what the includes contribute, and `API_CALL` is api.h's own `#define`"
    );
    assert_eq!(
        view.body_text_in_force("SA").map(str::trim),
        Some("id"),
        "`#ifdef __cplusplus` was answered as C++ in the walk, so the C++ spelling of `SA` is the one in force — \
         and a definition inside a taken branch is a **body**, not a definition, in both readings"
    );
    assert_eq!(
        per_file.body_text_in_force("SA").map(str::trim),
        Some("id"),
        "the per-file walk answered the same branch"
    );
    assert_eq!(
        view.body_text_of("API_CALL", source.len()),
        None,
        "a file's own facts are the parser's own reading in both readings — see `environment_at`'s contract"
    );
    // The record still *has* the fact, with the file and the offset it was written at: the exclusion is the
    // environment's, not the timeline's. (`range` is the **name**, deliberately — see `MacroFact` — so the offset
    // lands on `API_CALL` and not on the `#` that introduces it.)
    assert!(
        timeline
            .facts_of(Path::new("/p/api.h"))
            .any(|(name, at)| name == "API_CALL" && source[at..].starts_with("API_CALL")),
        "the timeline records what the file wrote, at the offset it wrote it"
    );
}

/// **A file's environment carries the state of the unit it is read in** — the difference from the per-file walk,
/// and the reason the timeline is not merely cheaper.
///
/// The old reading gave a header a context built from **one includer**, found by a breadth-first walk of the
/// corpus, and the doc records what that cost: six headers looked *broken* by a switch when each read cleanly on
/// real thing: the state of the translation unit at the `#include`.
///
/// So this test asserts a difference on purpose, in both directions, on one fixture.
#[test]
fn a_files_environment_carries_the_state_of_the_unit_it_is_read_in() {
    let files = [
        ("/p/api.h", "int inside = FROM_THE_SOURCE;\n"),
        (
            "/p/main.cpp",
            "#define FROM_THE_SOURCE 1\n#include \"api.h\"\n",
        ),
    ];

    let unit = Unit::new(&files);
    let mut definitions = MacroDefinitions::default();
    let per_file = unit.per_file("/p/api.h", &mut definitions);
    let timeline = unit.timeline_of("/p/main.cpp", &mut definitions);
    let view = timeline
        .environment_of(Path::new("/p/api.h"))
        .expect("the unit reaches api.h");

    assert_eq!(
        per_file.kind_of("FROM_THE_SOURCE", 0),
        None,
        "api.h's own closure says nothing about it — the name is the source file's"
    );
    assert!(
        view.kind_of("FROM_THE_SOURCE", 0).is_some(),
        "…and the unit that includes api.h has it in force, which is what the header really sees"
    );
    assert_eq!(
        view.body_text_of("FROM_THE_SOURCE", 0).map(str::trim),
        Some("1"),
        "with the body the compilation had"
    );
}

/// **A file is found in its timeline however its path is spelled** — the defect that made a header uncookable.
///
/// One file reaches these layers in two spellings: a directory scan hands the caller's (`C:\…\LSP.h`), an `#include`
/// that resolved hands the normalized one (`c:/…/lsp.h`), and the timeline cache is keyed by the normalized form — so
/// one unit can be written under one spelling and read back under the other. The frames were keyed raw, so
/// `environment_of` answered `None` for the file the unit was **built for**.
///
/// What that cost is not a missing hover: `render_a_cooked` declines on `environment_of(path)?`,
/// the cook slice drops the file instead of cooking it, and `want_the_closure_cooked` asks for it
/// again on the next idle drain — for ever.
#[test]
fn a_file_is_found_in_its_timeline_however_its_path_is_spelled() {
    let files = [
        ("/p/api.h", "int inside;\n"),
        ("/p/main.cpp", "#include \"api.h\"\n"),
    ];
    let unit = Unit::new(&files);
    let mut definitions = MacroDefinitions::default();
    let timeline = unit.timeline_of("/p/main.cpp", &mut definitions);

    assert!(
        timeline.environment_of(Path::new("/p/main.cpp")).is_some(),
        "the root is in its own timeline"
    );
    assert!(
        timeline.environment_of(Path::new("/p/api.h")).is_some(),
        "and so is the file it includes"
    );

    // **The same two files, spelled the way a directory scan and a cache entry spell them**: case and separators
    // differ, which is one file on this platform.
    #[cfg(windows)]
    for spelled_differently in ["\\p\\MAIN.CPP", "/P/Api.h"] {
        assert!(
            timeline
                .environment_of(Path::new(spelled_differently))
                .is_some(),
            "`{spelled_differently}` names a file this unit entered, so it must answer"
        );
    }
}

/// **A definition is in force from the `#include` that brought it in**, and the timeline's offsets say so.///
/// This is the property that makes the environment *positional*, and the one a careless timeline loses: if every
/// inherited definition is simply put at offset 0 — or worse, if the file's own offsets are used for a file that
/// wrote them somewhere else — a name becomes a macro before the line that defines it, and rules that read shape
/// because no table knows the name switch off for the whole file.
#[test]
fn an_included_definition_is_in_force_from_the_include() {
    let files = [
        ("/p/late.h", "#define LATE 1\n"),
        (
            "/p/user.h",
            "int before = LATE;\n#include \"late.h\"\nint after = LATE;\n",
        ),
    ];

    let unit = Unit::new(&files);
    let mut definitions = MacroDefinitions::default();
    let timeline = unit.timeline_of("/p/user.h", &mut definitions);
    let view = timeline.root_environment();

    let source = unit.sources.get(Path::new("/p/user.h")).expect("read");
    let include_end =
        source.find("#include \"late.h\"").expect("the include") + "#include \"late.h\"".len();

    assert_eq!(
        view.kind_of("LATE", include_end - 2),
        None,
        "before the include, nothing here has defined `LATE`"
    );
    assert!(
        view.kind_of("LATE", include_end + 2).is_some(),
        "after the include, it is a macro — from the end of the `#include`, not from offset 0"
    );
}

/// **A file the unit never reaches has no environment**, and that is an answer rather than a failure.
///
/// The per-file reading gives every file a closure of its own; the unit reading deliberately does not, because
/// "what does this file see" has no answer outside a translation unit that includes it. `None` is what says so,
/// and the caller that wants a context for such a file has to name the unit that gives it one.
#[test]
fn a_file_outside_the_unit_has_no_environment() {
    let files = [
        ("/p/api.h", "#define API 1\n"),
        ("/p/main.cpp", "#include \"api.h\"\n"),
        ("/p/unrelated.h", "#define UNRELATED 1\n"),
    ];

    let unit = Unit::new(&files);
    let mut definitions = MacroDefinitions::default();
    let timeline = unit.timeline_of("/p/main.cpp", &mut definitions);

    assert!(timeline.environment_of(Path::new("/p/api.h")).is_some());
    assert!(
        timeline
            .environment_of(Path::new("/p/unrelated.h"))
            .is_none(),
        "nothing includes it, so nothing here says what it sees"
    );
    assert_eq!(
        timeline.files().count(),
        2,
        "the walk entered the source and the header it includes, and nothing else"
    );
}

/// **One walk, not one per file** — the property the whole type exists for, asserted on the read log.
///
/// A count of reads is the only way to see this: two readings that reach the same environments produce the same
/// *answers*, and the difference is entirely in how many times the files were walked. `MemoryFiles` counts reads
/// for exactly this question (see its own note), so the test asks it directly.
#[test]
fn the_unit_walks_its_files_once() {
    let files = [
        ("/p/a.h", "#define A 1\n"),
        ("/p/b.h", "#include \"a.h\"\n#define B 1\n"),
        (
            "/p/c.h",
            "#include \"a.h\"\n#include \"b.h\"\n#define C 1\n",
        ),
        ("/p/main.cpp", "#include \"c.h\"\n"),
    ];

    let mut provider = MemoryFiles::new();
    for (path, text) in files {
        provider.insert(path, text);
    }
    let mut config = CompilerConfig::default();
    config = config.with_include_path(PathBuf::from("/p"));
    let indexer = FileIndexer::new(&provider, &config);
    let key = SummaryKey::new(0, 0);

    let mut summaries = HashMap::new();
    let mut sources = HashMap::new();
    for (path, text) in files {
        let path = PathBuf::from(path);
        summaries.insert(path.clone(), indexer.index(&path, text, key));
        sources.insert(path, (*text).to_string());
    }

    let mut seed = Marked::default();
    seed.define_on_the_command_line("__cplusplus", Some("202002L"));
    let look_up = |wanted: &Path| {
        Some((
            summaries.get(wanted)?,
            sources.get(wanted).map(String::as_str).unwrap_or(""),
        ))
    };
    let mut definitions = MacroDefinitions::default();
    let timeline = TranslationUnit::walk(
        summaries.get(Path::new("/p/main.cpp")).expect("indexed"),
        look_up,
        &seed,
        &mut definitions,
        false,
        &cpp_code_analysis::WalkCache::new(),
    );

    // **Every file is read at most once**, which is the walk's promise about *reading*: a summary is what a file is
    // read into, and the per-file reading used to read the closure of each file (`a.h` once per consumer). The walk
    // reads the summaries; the frames below are entries, not reads.
    for path in ["/p/a.h", "/p/b.h", "/p/c.h", "/p/main.cpp"] {
        assert!(
            provider.reads_of(path) <= 1,
            "{path} was read {} times for one unit",
            provider.reads_of(path)
        );
    }

    // **A frame per *entry*, which is not a file per frame.** `a.h` is included twice (`c.h` and `b.h` both take it)
    // and it has no guard — `#define A 1` and nothing else — so a preprocessor reads it twice, and this walk now says
    // so. That is the rule `walk_one_file` states: the second read is decided by the **file's own text** (`#pragma
    // once`, or the `#ifndef X / #define X` idiom whose name the walk recognises), never by the walk's own memory of
    // having been there. Skipping it in the walk was wrong for every *unguarded* file, and libstdc++'s
    // `bits/version.h` — included by every header to add its own feature-test macros — is exactly such a file: see
    // `an_unguarded_header_is_read_again_and_defines_what_its_second_reader_asked_for`.
    let frames: Vec<&Path> = timeline.files().collect();
    assert_eq!(frames.len(), 5, "four files, five entries: {frames:?}");
    assert_eq!(
        frames
            .iter()
            .filter(|path| **path == Path::new("/p/a.h"))
            .count(),
        2,
        "`a.h` has no guard, so both includes read it: {frames:?}"
    );
}

/// **A file with no guard is read again, and what its second read defines is in force for the second reader.**
///
/// This is libstdc++'s `bits/version.h` in miniature, and the whole of `import std;`'s missing `std::println`: the
/// file is an *override header* — it defines whatever feature-test macro the header that includes it asked for, and
/// it is deliberately not guarded, because the second include is the point. A walk that reads each file once sees
/// only the first reader's request: `HAS_PRINT` never exists, `print`'s body (`#ifdef HAS_PRINT`) is dropped, and its
/// summary holds 0 declarations.
#[test]
fn an_unguarded_header_is_read_again_and_defines_what_its_second_reader_asked_for() {
    let files = [
        (
            "/p/version.h",
            "#ifdef WANT_PRINT\n#define HAS_PRINT 1\n#endif\n",
        ),
        ("/p/print.h", "#define WANT_PRINT\n#include \"version.h\"\n"),
        (
            "/p/a.h",
            "#include \"version.h\"\n#ifdef HAS_PRINT\nint a_print;\n#endif\n",
        ),
        (
            "/p/b.h",
            "#include \"print.h\"\n#ifdef HAS_PRINT\nint b_print;\n#endif\n",
        ),
        ("/p/main.cpp", "#include \"a.h\"\n#include \"b.h\"\n"),
    ];

    let mut provider = MemoryFiles::new();
    for (path, text) in files {
        provider.insert(path, text);
    }
    let mut config = CompilerConfig::default();
    config = config.with_include_path(PathBuf::from("/p"));
    let indexer = FileIndexer::new(&provider, &config);
    let key = SummaryKey::new(0, 0);

    let mut summaries = HashMap::new();
    let mut sources = HashMap::new();
    for (path, text) in files {
        let path = PathBuf::from(path);
        summaries.insert(path.clone(), indexer.index(&path, text, key));
        sources.insert(path, (*text).to_string());
    }

    let seed = Marked::default();
    let look_up = |wanted: &Path| {
        Some((
            summaries.get(wanted)?,
            sources.get(wanted).map(String::as_str).unwrap_or(""),
        ))
    };
    let mut definitions = MacroDefinitions::default();
    let timeline = TranslationUnit::walk(
        summaries.get(Path::new("/p/main.cpp")).expect("indexed"),
        look_up,
        &seed,
        &mut definitions,
        false,
        &cpp_code_analysis::WalkCache::new(),
    );

    // **`version.h` was entered twice**, once from each reader's chain, and the second entry — the one `print.h`
    // makes — is the one that asks for `HAS_PRINT`. So `b.h`, which reaches it through `print.h`, has the macro; and
    // `a.h`, whose chain asked for nothing, does not. That asymmetry *is* the semantics: a walk that reads each file
    // once gives `b.h` the same answer as `a.h`, which is what made `print`'s declarations disappear.
    let at_the_end = |path: &str| sources.get(Path::new(path)).map_or(0, String::len);
    let a = timeline
        .environment_of(Path::new("/p/a.h"))
        .expect("`a.h` has an environment");
    assert!(
        a.kind_of("HAS_PRINT", at_the_end("/p/a.h")).is_none(),
        "`a.h` asked `version.h` for nothing, so nothing was defined"
    );
    let b = timeline
        .environment_of(Path::new("/p/b.h"))
        .expect("`b.h` has an environment");
    assert!(
        b.kind_of("HAS_PRINT", at_the_end("/p/b.h")).is_some(),
        "`b.h` reaches `version.h` through `print.h`, which asks for `HAS_PRINT` — the second read is the one that \
         defines it"
    );
}

// **A unit can be kept and read back** — the cache layer's acceptance, on a fixture rather than a corpus.
//
// Three properties, and the second is the one that makes it usable rather than merely fast:
//
// 1. an entry written by one run is served to the next;
// 2. what is served **answers exactly like what was walked** — a cache of macro state that decodes into a
//    slightly different timeline produces a *reading*, not a diagnostic, and every rule downstream would then
//    answer about a header nobody has;
// 3. a file in the closure whose contents moved **refuses** the entry, which is the whole validity key.
// **`a_walked_unit_can_be_kept_and_read_back` is gone, with the cache it tested.** A built timeline is no
// longer persisted: it outlives the files it was built from, and rebuilding one is 38 ms — see
// `Session::translation_unit_of`. The other tests in this file are about the walk itself, which is unchanged.
/// **The unit cooks as one program**, not as a pile of headers.
///
/// Cooking one file at a time answers "does this header read on its own" — it cannot answer "does the program
/// read", because a declaration in one file and a use in another are two streams with nothing tying them
/// together. `cook_the_unit` is that stream: the walk's own order (which is include order) with each include
/// spliced in where the `#include` ended, and a map that says which file every token stands in.
#[test]
fn the_unit_cooks_as_one_stream_in_include_order() {
    let files = [
        ("/p/config.h", "#define WIDTH 4\nstruct Cfg { int a; };\n"),
        (
            "/p/api.h",
            "#include \"config.h\"\n#define API WIDTH\nstruct Api { Cfg c; };\n",
        ),
        ("/p/main.cpp", "#include \"api.h\"\nint main_use = API;\n"),
    ];

    let unit = Unit::new(&files);
    let mut definitions = MacroDefinitions::default();
    let timeline = unit.timeline_of("/p/main.cpp", &mut definitions);
    let shared = timeline.definitions();

    let stitched = timeline.cook_the_unit(&unit.sources, &shared, None, true, None);
    assert_eq!(
        stitched.missing, 0,
        "every file the unit reached has text here"
    );
    assert_eq!(
        stitched.files_with_tokens(),
        3,
        "all three files contributed a token: {}",
        stitched.text
    );

    // The order is the walk's: what a file includes comes before its own text, and a header's own include comes
    // before the header's.
    let at = |needle: &str| {
        stitched
            .text
            .find(needle)
            .unwrap_or_else(|| panic!("`{needle}` is in the stream: {}", stitched.text))
    };
    assert!(at("struct Cfg") < at("struct Api"), "{}", stitched.text);
    assert!(at("struct Api") < at("main_use"), "{}", stitched.text);

    // **It is a program**: `Cfg` is a type the stream declared one file earlier, `API` came from a header and
    // expanded to a value `config.h` defines, and the whole thing parses.
    let tree = cpp_parser::CppParser::parse(&stitched.text, cpp_parser::ParserConfig::default());
    assert!(
        tree.get_errors().is_empty(),
        "the stitched unit has errors: {:?} in {}",
        tree.get_errors(),
        stitched.text
    );
    // **The expansion, asserted as a fact about names rather than about spaces.** This used to look for `"= 4 ;"`,
    // which is a claim about where the renderer puts a semicolon — the stream spells `int main_use = 4;`, so the
    // test was red while `API` had in fact expanded two files away, exactly as its own message says. Naming both
    // halves is strictly more than the spacing check was: the value is there **and** neither macro's name survived
    // into the program, which is what an unexpanded invocation would look like.
    assert!(
        stitched.text.contains("= 4"),
        "`API` expanded to `WIDTH`'s value, which is defined two files away: {}",
        stitched.text
    );
    for name in ["API", "WIDTH"] {
        assert!(
            !stitched.text.contains(name),
            "`{name}` is gone from the stream, replaced by what it stands for: {}",
            stitched.text
        );
    }

    // **The map says which file a token stands in**, and where in that file to act: `Api` is api.h's text…
    let api = Path::new("/p/api.h");
    let api_text = unit.sources.get(api).expect("read");
    let api_at = stitched.text.find("Api").expect("in the stream");
    let (file, written) = stitched.written_at(api_at).expect("a token is there");
    assert_eq!(stitched.file_of(file), Some(api));
    assert_eq!(&api_text[written.start_offset..written.end_offset()], "Api");

    // …and the `4`, which was written in `config.h` and pasted by a macro `api.h` defines, **stands in
    // main.cpp**: that is where the reader can act on it, and the map points at the call site.
    //
    // **Found by the digit, not by the spaces around it.** This asked for `" 4 "`, which is a claim about the
    // renderer's whitespace — the stream spells `int main_use = 4;` — so it was red while the expansion it is named
    // after was right there. The fixture has no other `4`, so the digit itself is the unambiguous anchor and the
    // spacing stops being part of the contract.
    let main = Path::new("/p/main.cpp");
    let main_text = unit.sources.get(main).expect("read");
    let four = stitched
        .text
        .find('4')
        .expect("the expansion is in the stream");
    let (file, written) = stitched.written_at(four).expect("a token is there");
    assert_eq!(
        stitched.file_of(file),
        Some(main),
        "a macro's token stands in the file that invoked it"
    );
    assert_eq!(
        written.start_offset,
        main_text.find("API").expect("the invocation"),
        "and it points at the call site, not at a body in another file"
    );
}

/// **A declaration that begins with a token out of another file's macro body is still that file's declaration.**
///
/// The contract [`RenderedUnit::written_span`] needs: **the file an answer names and the range it gives are two
/// facts about one text**, so the range has to end inside it.
///
/// A `UnitSpan` carries two different things, and answering with the wrong one would be silent:
///
/// ```text
/// span.file     which file's cook produced the token — the file it **stands in**, and the only thing that
///               can say which file a declaration is in
/// span.written  where to act on it — the token's own range, or the call site for one a macro produced
/// ```
///
/// The shape that separates them is a declaration whose **whole text came out of another file's macro body**: the
/// invocation `DECLARE_WIDGET` is what `decl.h` wrote, and the `struct Widget { … }` in the stream is `macros.h`'s
/// text pasted in. Read the file out of the *hint* and the answer is a position in `macros.h`'s body while the
/// declaration stands in `decl.h`.
///
/// **It is not a live bug, and this test is why that is a measurement rather than a belief.**
/// `ExpandedToken::diagnostic_range` already answers with the **outermost call site** — a position in the invoking
/// file — so the hint and the standing file agree, and the assertion below holds on this crate's implementation.
/// Nothing *enforced* it before: the failure this class of answer produced elsewhere was a 93 971-byte class body
/// filed under a 1.2 KB header with every other field of the fact correct. So the test pins the invariant rather
/// than a past mistake, and [`RenderedUnit::span_lands_in`] is the check that turns a future violation into a
/// counted `unplaced` instead of a wrong answer.
#[test]
fn a_declaration_starts_in_the_file_it_stands_in() {
    let files = [
        (
            "/p/macros.h",
            "#define DECLARE_WIDGET struct Widget { int size; };\n",
        ),
        (
            "/p/decl.h",
            "#include \"macros.h\"\nnamespace outer {\nDECLARE_WIDGET\n}\n",
        ),
        ("/p/main.cpp", "#include \"decl.h\"\nint use = 0;\n"),
    ];

    let unit = Unit::new(&files);
    let mut definitions = MacroDefinitions::default();
    let timeline = unit.timeline_of("/p/main.cpp", &mut definitions);
    let shared = timeline.definitions();
    let stream = timeline.cook_the_unit(&unit.sources, &shared, None, true, None);

    // The stream has the expansion, not the invocation: `decl.h` wrote a name, the stream has a struct.
    assert!(
        stream.text.contains("struct Widget { int size ; } ;"),
        "the macro expanded into the stream: {}",
        stream.text
    );

    let tree = cpp_parser::CppParser::parse(&stream.text, cpp_parser::ParserConfig::default());
    let widget = tree
        .get_red_root()
        .descendants()
        .find(|node| {
            cpp_parser::CppSyntaxKind::from(node.kind()) == cpp_parser::CppSyntaxKind::StructDef
        })
        .expect("the struct is in the stream");
    let range = cpp_parser::source_range(widget.text_range());

    let (file, written) = stream.written_span(range).expect("it maps");
    assert_eq!(
        stream.file_of(file),
        Some(Path::new("/p/decl.h")),
        "the declaration **stands in** decl.h, which is the file whose invocation produced it"
    );

    // …and the answer lands in that file — the invariant a hint from another file would break. Asked as a bounds
    // check rather than through `span_lands_in` so that the test puts the question to the mapping itself, which is
    // the layer a consumer reads; `span_lands_in` is what the index asks on every fact.
    let decl = &unit.sources[Path::new("/p/decl.h")];
    let acted_on = decl
        .get(written.start_offset..written.end_offset())
        .unwrap_or_else(|| {
            panic!(
                "the answer does not land in the file it names: {written:?} of {} bytes",
                decl.len()
            )
        });
    assert!(
        acted_on.contains("DECLARE_WIDGET"),
        "the range is the declaration as that file spells it — the invocation, not the body: {acted_on:?}"
    );
}

/// **Taking a file out of the stream keeps every offset where it was.**
///
/// The quarantine path blanks a file's tokens instead of deleting them, and the difference is not cosmetic: the
/// parse that follows maps its declarations back through the **original** span table, so a stream that came out
/// six kilobytes shorter moved every later offset by six kilobytes and filed every declaration after it under the
/// wrong file. Measured on a project that includes `<string>`: `basic_string`'s 93 971-byte class body — the one
/// written in `<xstring>` — was filed under `<__msvc_formatter.hpp>`, whose *forward declaration* of the same name
/// stands 6 100 bytes earlier. Nothing downstream could notice: the name was right, the scope was right, and the
/// range was right for the wrong file.
///
/// Three properties, and each one is what the mapping needs:
///
/// ```text
/// the text is the same length          so an offset in the result is an offset in the original
/// the spans are the original ones      so `written_span` answers about the text that is still there
/// the token is gone from the *parse*   so the file contributes nothing but spaces
/// ```
///
/// **The unit reader no longer does this**, and the reason is worth knowing before reading this as a description of
/// the pipeline: taking a file out of a program because one of its braces was mis-paired costs every declaration in
/// the file, and that is the plan's gate ①. The reader gives up the **pairing** instead
/// (`RenderedUnit::neutralized`: two braces become markers that pair with nothing) and reads the file on its own as
/// well. What survives here is `without`'s own contract, which is still the right answer to "what would this program
/// be without that file" — and the length-preservation it shares with `neutralized` is the property that makes both
/// of them usable.
#[test]
fn taking_a_file_out_of_the_stream_keeps_the_offsets() {
    let files = [
        ("/p/first.h", "struct First { int a; };\n"),
        ("/p/leaky.h", "struct Leaky { int b; };\n"),
        ("/p/third.h", "struct Third { int c; };\n"),
        (
            "/p/main.cpp",
            "#include \"first.h\"\n#include \"leaky.h\"\n#include \"third.h\"\nint use = 1;\n",
        ),
    ];

    let unit = Unit::new(&files);
    let mut definitions = MacroDefinitions::default();
    let timeline = unit.timeline_of("/p/main.cpp", &mut definitions);
    let shared = timeline.definitions();
    let whole = timeline.cook_the_unit(&unit.sources, &shared, None, true, None);

    let leaky = whole
        .files
        .iter()
        .position(|path| path == Path::new("/p/leaky.h"))
        .expect("the file is in the unit") as u32;
    let mut left_out = std::collections::BTreeSet::new();
    left_out.insert(leaky);
    let without = whole.without(&left_out);

    assert_eq!(
        without.text.len(),
        whole.text.len(),
        "the text is the same length, which is what keeps every offset where it was"
    );
    assert_eq!(
        without.text.find("Third"),
        whole.text.find("Third"),
        "so a declaration after the left-out file is found at the same place"
    );
    assert!(
        !without.text.contains("Leaky"),
        "and the left-out file's own tokens are gone: {}",
        without.text
    );

    // **The mapping still answers about the text that is there**, which is the property the index depends on.
    let third = without.text.find("Third").expect("still in the stream");
    let (file, written) = without
        .written_span(cpp_parser::SourceRange::new(third, 5))
        .expect("mapped");
    assert_eq!(
        without.file_of(file),
        Some(Path::new("/p/third.h")),
        "a token after the left-out file still belongs to its own file"
    );
    assert_eq!(
        written.start_offset,
        "struct Third { int c; };\n"
            .find("Third")
            .expect("its own text"),
        "and to its own offset in that file, not to where it stands in the stream"
    );

    // …and the program without it still parses.
    let tree = cpp_parser::CppParser::parse(&without.text, cpp_parser::ParserConfig::default());
    assert!(tree.get_errors().is_empty(), "{:?}", tree.get_errors());
}

/// **A file that does not balance its braces contributes its tokens anyway, and is named.**
///
/// This is the plan's gate ①, and it used to be all-or-nothing: a frame whose own tokens did not balance was
/// **left out of the stream** entirely, on the reasoning that keeping the text would let its unclosed scope swallow
/// every file spliced after it. The hazard was real and the price was not — a file with one unbalanced brace and
/// eight hundred good declarations contributed **none** of them, which is §4 rule 1 broken in the same way the
/// `crossings == 0` gate broke it one layer up.
///
/// So the text goes in and the crossed pairing is repaired one layer up
/// (`FileIndexer::index_unit_rendering`). This test is at the **cook** level, where the decision is made, and it
/// pins the three things that have to hold together:
///
/// ```text
/// the tokens are in the stream           so the file's declarations can be found at all
/// the file is named in `unbalanced`      so a consumer can doubt it — rule 3
/// the stream does not balance either     which is why the repair one layer up is load-bearing, not optional
/// ```
///
/// The third is the one worth stating out loud: including the text means the **whole-program stream** now carries
/// the imbalance, and the only thing that keeps the next file out of the leaked scope is that the reader finds the
/// crossed brace pair and gives it up. A change that made `brace_crossings` miss this shape would move `Second`
/// inside `Leaky` — so the session-level test
/// (`a_file_that_does_not_balance_its_braces_is_named_and_still_read`) asserts the other end of it.
#[test]
fn a_file_that_does_not_balance_still_contributes_its_tokens() {
    let files = [
        // Opens a namespace and never closes it: what a `/analyze` header does, and what swallows a program.
        (
            "/p/leaky.h",
            "namespace vc_attributes {\nstruct First { int a; };\n",
        ),
        ("/p/second.h", "struct Second { int b; };\n"),
        (
            "/p/main.cpp",
            "#include \"leaky.h\"\n#include \"second.h\"\n",
        ),
    ];

    let unit = Unit::new(&files);
    let mut definitions = MacroDefinitions::default();
    let timeline = unit.timeline_of("/p/main.cpp", &mut definitions);
    let shared = timeline.definitions();
    let stitched = timeline.cook_the_unit(&unit.sources, &shared, None, true, None);

    // The tokens are in: this is the half gate ① used to take away.
    assert!(
        stitched.text.contains("First"),
        "the unbalanced file's own declaration is in the stream: {}",
        stitched.text
    );
    assert!(
        stitched.text.contains("Second"),
        "and so is the file after it: {}",
        stitched.text
    );

    // It is named, which is what a consumer has to be able to see.
    assert_eq!(
        stitched.unbalanced,
        vec![PathBuf::from("/p/leaky.h")],
        "the file that does not balance is named, and only it"
    );

    // **And the stream carries the imbalance**, which is the fact the repair one layer up exists for. `braces` is
    // `{` minus `}` over the whole stream, so a file that opened one scope too many leaves it **positive** — one
    // closer short, counted backwards.
    assert!(
        stitched.braces > 0,
        "an unclosed `{{` leaves the whole stream one closer short, so the repair is load-bearing: {}",
        stitched.braces
    );

    // Every token still maps back to the file it was written in — the property the whole mapping rests on, and the
    // one a stream built by *skipping* a file never had to be asked about.
    let second = stitched
        .text
        .find("Second")
        .expect("the file after the unbalanced one is in the stream");
    let (file, written) = stitched
        .written_span(cpp_parser::SourceRange::new(second, "Second".len()))
        .expect("mapped");
    assert_eq!(
        stitched.file_of(file),
        Some(Path::new("/p/second.h")),
        "a token after the unbalanced file still belongs to its own file"
    );
    assert_eq!(
        written.start_offset,
        "struct Second { int b; };\n"
            .find("Second")
            .expect("its own text"),
        "and to its own offset in that file"
    );
}

/// **A file the caller has no text for is a hole, not an empty file.**
///
/// The two produce different programs, and a census that conflated them would report "the unit parses" about a
/// unit it never read. The hole is counted, the files it named are still stitched (the walk reached them through
/// it), and nothing is invented for the missing file.
#[test]
fn a_file_without_text_is_a_hole_in_the_unit() {
    let files = [
        ("/p/config.h", "#define WIDTH 4\nstruct Cfg { int a; };\n"),
        (
            "/p/api.h",
            "#include \"config.h\"\nstruct Api { int a[WIDTH]; };\n",
        ),
        ("/p/main.cpp", "#include \"api.h\"\n"),
    ];

    let unit = Unit::new(&files);
    let mut definitions = MacroDefinitions::default();
    let timeline = unit.timeline_of("/p/main.cpp", &mut definitions);
    let shared = timeline.definitions();

    // The same unit, with `api.h`'s text withheld — the shape of an editor whose buffer for it is not loaded.
    let mut partial: HashMap<PathBuf, String> = unit.sources.clone();
    partial.remove(Path::new("/p/api.h"));

    let stitched = timeline.cook_the_unit(&partial, &shared, None, true, None);
    assert_eq!(stitched.missing, 1, "api.h was reached and not read");
    assert!(
        !stitched.text.contains("Api"),
        "nothing was invented for the missing file: {}",
        stitched.text
    );
    assert!(
        stitched.text.contains("Cfg"),
        "and the file *it* included is still stitched, because the walk reached it through the hole: {}",
        stitched.text
    );
}

/// **A macro that declares a type is a declaration in the cooked reading, and points at the invocation.**
///
/// This is the whole reason the index reads the cooked stream: `DECLARE_HANDLE(HWND)` declares `HWND__` and
/// `HWND` to a compiler and *nothing* to a reader of the file's own text, because the declaration is inside the
/// 3 250 declaration names that exist only after expansion — `DECLARE_HANDLE`'s generated structs and members,
/// and — the larger half — the *scopes*: every declaration between `_STD_BEGIN` and `_STD_END` is `std::`-qualified
/// in the cooked reading and at file scope in the raw one, which is the difference between a lookup that finds
/// `std::to_string` and one that does not.
#[test]
fn a_macro_that_declares_a_type_declares_it_in_the_cooked_reading() {
    let declaration = "#define DECLARE_HANDLE(name) struct name##__ { int unused; }; \
                       typedef struct name##__ *name\n";
    let files = [
        ("/p/decl.h", declaration),
        ("/p/api.h", "#include \"decl.h\"\nDECLARE_HANDLE(HWND);\n"),
    ];

    let unit = Unit::new(&files);
    let mut definitions = MacroDefinitions::default();
    let timeline = unit.timeline_of("/p/api.h", &mut definitions);
    let shared = timeline.definitions();
    let config = CompilerConfig::default();
    let indexer = FileIndexer::new(&unit.files, &config);
    let key = SummaryKey::new(0, 0);

    let api = Path::new("/p/api.h");
    let source = unit.sources.get(api).expect("read");

    // **The raw reading**: the file's own text. `DECLARE_HANDLE(HWND);` is an invocation, and the declaration it
    // stands for is inside `decl.h`'s `#define`, where nothing this file declares lives.
    let raw = indexer.index(api, source, key);
    let raw_names: Vec<&str> = raw.declarations.iter().map(|fact| &*fact.name).collect();
    assert!(
        !raw_names.contains(&"HWND__") && !raw_names.contains(&"HWND"),
        "the raw reading cannot see a declaration that is inside a macro body: {raw_names:?}"
    );

    // **The cooked reading**: the program a compiler sees, indexed and mapped back into the file.
    let (tokens, _) = cpp_parser::lex(source, &cpp_parser::LexerConfig::default());
    let macros = cpp_code_analysis::FileMacros::new(
        timeline
            .environment_of(api)
            .expect("the unit reaches api.h"),
        &shared,
        None,
        true,
    );
    let cooked = cpp_code_analysis::cook_with(source, &tokens, &macros);
    let rendered = cooked.render();
    assert!(
        rendered.text.contains("HWND__"),
        "the rendering has the declaration: {}",
        rendered.text
    );

    let indexed = indexer.index_rendering(api, &rendered, key);
    let cooked_summary = &indexed.summary;
    let report = indexed.mapped;
    let cooked_names: Vec<&str> = cooked_summary
        .declarations
        .iter()
        .map(|fact| &*fact.name)
        .collect();
    assert!(
        cooked_names.contains(&"HWND__"),
        "the struct the macro declares is a declaration here: {cooked_names:?}"
    );
    assert!(
        cooked_names.contains(&"HWND"),
        "…and the typedef beside it: {cooked_names:?}"
    );
    assert_eq!(report.dropped, 0, "every range landed in the file");
    assert!(report.placed > 0);

    // **And the range points at the invocation**, which is the only place in this file a reader can act on: the
    // declaration's text is in `decl.h`, and `map_into_the_file` reports the call site for exactly that reason.
    let hwnd = cooked_summary
        .declarations
        .iter()
        .find(|fact| fact.name == "HWND__")
        .expect("declared");
    let written = &source[hwnd.range.start_offset..hwnd.range.end_offset()];
    assert!(
        written.contains("DECLARE_HANDLE"),
        "the declaration is reported at the invocation: {written:?}"
    );
}

/// **A definition knows which file it was written in.**
///
/// A `MacroDef` used to be ranges and nothing else, which is a lie in two of the three places a definition can
/// come from: one read from a file is in that file, one that arrived from another file of a walked unit is in
/// *that* file, and one reconstructed from text alone is in no file at all. The map back to files is what made
/// the difference visible — a body token of an inherited macro was reported at its offset in the
/// reconstruction, a position in no file, which a consumer then slices into the file it has.
///
/// This test walks the whole path: the unit reads a definition out of `config.h`, `api.h` invokes it, the source
/// file invokes *that*, and the token the reader ends up with says where each hop was written.
#[test]
fn a_definition_says_which_file_it_was_written_in() {
    let files = [
        ("/p/config.h", "#define WIDTH 4\n"),
        ("/p/api.h", "#include \"config.h\"\n#define API WIDTH\n"),
        ("/p/main.cpp", "#include \"api.h\"\nint v = API;\n"),
    ];

    let unit = Unit::new(&files);
    let mut definitions = MacroDefinitions::default();
    let timeline = unit.timeline_of("/p/main.cpp", &mut definitions);
    let shared = timeline.definitions();

    let main = Path::new("/p/main.cpp");
    let text = unit.sources.get(main).expect("read");
    let (tokens, _) = cpp_parser::lex(text, &cpp_parser::LexerConfig::default());
    let macros = cpp_code_analysis::FileMacros::new(
        timeline
            .environment_of(main)
            .expect("the unit reaches main.cpp"),
        &shared,
        None,
        true,
    );
    let cooked = cpp_code_analysis::cook_with(text, &tokens, &macros);
    let rendered = cooked.render();

    // The `4`: written in `config.h`'s `#define WIDTH 4`, pasted by `api.h`'s `#define API WIDTH`, invoked in
    // main.cpp.
    let four = cooked
        .tokens
        .iter()
        .find(|token| token.text() == "4")
        .expect("the expansion is in the stream");
    // **Anchored on the digit rather than on the spaces around it.** This used to search for `" 4 "`, which is a
    // claim about the renderer's whitespace and not about the expansion: the stream spells `int v = 4;`, so the
    // assertion was red while the thing it is named after — "the expansion is in the rendering" — was true, and the
    // token above had already been found. Three tests in this file broke on exactly that, which is what a formatting
    // assertion does the first time a renderer's spacing moves. This fixture has no other `4`.
    let at = rendered
        .text
        .find('4')
        .expect("the expansion is in the rendering");

    // **Where it was written is not this file**, and the map says so rather than handing over an offset that
    // belongs to a reconstruction.
    assert_eq!(
        rendered.written_at(at),
        None,
        "the spelling of `4` is in config.h, not in main.cpp"
    );
    // **Where to report it is this file**: the invocation the reader can see.
    let reported = rendered.reported_at(at).expect("a place to report");
    assert_eq!(
        &text[reported.start_offset..reported.end_offset()],
        "API",
        "a diagnostic lands on the call site"
    );

    // **Navigation lands in the right file**: the innermost definition that can be pointed at is `WIDTH`, and it
    // is in `config.h` — a consumer turns the frame into a path and opens it.
    let (file, name_at) = four.navigation_at().expect("a definition in a file");
    let config = Path::new("/p/config.h");
    let cpp_code_analysis::macros::MacroFile::Frame(frame) = file else {
        panic!("`WIDTH` was not written in the file being cooked: {file:?}");
    };
    assert_eq!(
        timeline.frame_file(frame),
        Some(config),
        "the frame names config.h"
    );
    let config_text = unit.sources.get(config).expect("read");
    assert_eq!(
        &config_text[name_at.start_offset..name_at.end_offset()],
        "WIDTH",
        "and the range is the macro's name, in that file"
    );

    // **A macro the file itself wrote is in the file itself**: the other side of the same question, on one
    // fixture, so that "the map says another file" cannot pass by saying it everywhere.
    let local = [("/p/local.cpp", "#define HERE 7\nint v = HERE;\n")];
    let unit = Unit::new(&local);
    let mut definitions = MacroDefinitions::default();
    let timeline = unit.timeline_of("/p/local.cpp", &mut definitions);
    let shared = timeline.definitions();
    let path = Path::new("/p/local.cpp");
    let text = unit.sources.get(path).expect("read");
    let (tokens, _) = cpp_parser::lex(text, &cpp_parser::LexerConfig::default());
    let macros = cpp_code_analysis::FileMacros::new(
        timeline.environment_of(path).expect("reached"),
        &shared,
        None,
        true,
    );
    let cooked = cpp_code_analysis::cook_with(text, &tokens, &macros);
    let rendered = cooked.render();
    let seven = cooked
        .tokens
        .iter()
        .find(|token| token.text() == "7")
        .expect("the expansion");
    let at = rendered.text.find('7').expect("in the rendering");
    let written = rendered.written_at(at).expect("written in this file");
    assert_eq!(
        &text[written.start_offset..written.end_offset()],
        "7",
        "a body token of a file's own macro is at the body, in this file"
    );
    assert_eq!(
        seven.navigation_at().expect("a definition in a file").0,
        cpp_code_analysis::macros::MacroFile::Here
    );
}

/// **A file cooks the same through the unit as through a table of its own.**
///
/// The one-walk path stopped building a table per file: it reads the unit's definitions **once**
/// ([`TranslationUnit::definitions`]) and answers each query positionally (`FileMacros`). That is a different
/// mechanism for the same question, and the only thing that matters about it is that the answer is the same — a
/// binding that is in force in one reading and not in the other changes what the cooker pastes, which shows up
/// much later as a parse that reads something else.
///
/// So this test cooks every file of a fixture **twice**: once from the shared unit, once from the table the
/// per-file reading built, and compares the rendered text byte for byte. The fixture is chosen to put every layer
/// of the new state under the comparison: a definition inside a taken `#if` (the in-force channel, which is the
/// newest layer), a conditional definition the seed decides, an `#undef` in the middle of a file (which must
/// shadow what the include brought in from that offset on), and a name the seed also carries.
#[test]
fn a_file_cooks_the_same_through_the_unit_as_through_a_table_of_its_own() {
    let files = [
        (
            "/p/config.h",
            "#ifndef _CONFIG_H_\n\
             #define _CONFIG_H_\n\
             #ifdef __cplusplus\n\
             #define SA(id) id\n\
             #else\n\
             #define SA(id) SA_##id\n\
             #endif\n\
             #define OBJECT 1\n\
             #endif\n",
        ),
        (
            "/p/api.h",
            "#include \"config.h\"\n\
             #define LATE(x) (x)\n\
             int f = OBJECT + LATE(2);\n\
             #undef OBJECT\n\
             int g = SA(GG);\n",
        ),
        (
            "/p/main.cpp",
            "#include \"api.h\"\n\
             #define LATE(x) [x]\n\
             int h = OBJECT;\n\
             LATE(3)\n",
        ),
    ];

    let unit = Unit::new(&files);
    let mut definitions = MacroDefinitions::default();
    let timeline = unit.timeline_of("/p/main.cpp", &mut definitions);

    // The unit's definitions, read once — what replaced the per-file table build.
    let shared = timeline.definitions();

    let mut rendered_something_the_reading_can_be_told_apart_by = false;

    for (path, text) in &files {
        let path = Path::new(path);
        let view = timeline
            .environment_of(path)
            .unwrap_or_else(|| panic!("the unit reaches {}", path.display()));

        // The reading that builds a table for this file…
        let mut per_file_definitions = cpp_code_analysis::ParsedDefinitions::new();
        let configuration = cpp_code_analysis::configuration_from_environment_and(
            &view,
            true,
            &mut per_file_definitions,
        );

        // …and the reading that reads the unit once and answers positionally.
        let file_macros = cpp_code_analysis::FileMacros::new(view, &shared, None, true);

        let (tokens, _) = cpp_parser::lex(text, &cpp_parser::LexerConfig::default());
        let from_the_table = cpp_code_analysis::cook_with(text, &tokens, &configuration.table);
        let from_the_unit = cpp_code_analysis::cook_with(text, &tokens, &file_macros);

        // The precondition of the comparison, asserted rather than assumed: this file really does expand
        // something from outside itself, so "they agree" is not "both rendered an empty stream". (A header of
        // nothing but directives renders to nothing, and that is correct — `config.h` is exactly that.)
        rendered_something_the_reading_can_be_told_apart_by |=
            !from_the_table.render().text.trim().is_empty();

        assert_eq!(
            from_the_unit.render().text,
            from_the_table.render().text,
            "{} cooked differently through the unit than through its own table",
            path.display()
        );
    }

    assert!(
        rendered_something_the_reading_can_be_told_apart_by,
        "the fixture rendered nothing at all, so the comparison above was vacuous"
    );

    // **The seed is the oldest layer**, and the order is the whole of what makes the shared state equal to the
    // table it replaced: a name the unit defines wins over the compiler's own, a name the unit says nothing about
    // still comes from the seed, and a name the unit has **said something else** about is settled by that and not
    // by the seed.
    //
    // Asked of `main.cpp`'s view, and that is the point rather than a detail: `config.h`'s own `#define`s are not
    // in `config.h`'s environment — a file does not inherit its own facts, which is the contract
    // `TranslationUnit::environment_at` documents and the parser relies on (it reads the file's own `#define`s out
    // of the text). `main.cpp` includes `api.h`, so for *it* those facts are the unit's.
    let builtins = "#define LATE 99\n#define OBJECT 99\n#define _FROM_THE_SEED_ 1\n";
    let (tokens, _) = cpp_parser::lex(builtins, &cpp_parser::LexerConfig::default());
    let seed = cpp_code_analysis::preprocess::preprocess(builtins, &tokens).macros;

    let body_of = |definition: &cpp_code_analysis::macros::MacroDef| -> String {
        definition
            .body
            .significant()
            .map(|token| token.text().to_string())
            .collect()
    };
    let with_seed =
        cpp_code_analysis::FileMacros::new(timeline.root_environment(), &shared, Some(&seed), true);

    assert_eq!(
        with_seed.definition("LATE").map(body_of),
        Some("(x)".to_string()),
        "api.h's `#define LATE(x) (x)` arrives through the include and is in force over the seed's `99` \
         (main.cpp's own `LATE(x) [x]` is the *own* layer, which the cook adds — not this one)"
    );
    assert!(
        with_seed.definition("_FROM_THE_SEED_").is_some(),
        "a name only the seed defines still reaches the cook — that is what the oldest layer is for"
    );
    // **A gap this round did not change, asserted so that it stays visible.** api.h `#undef`s `OBJECT`, and the
    // unit knows it — but the cook's table has no way to say "not defined": an entry that said so would have to
    // shadow the seed, and the environment's `#undef` facts are not entries at all (an `#undef` is not a
    // definition, which is what `for_each_definition` yields). So the seed's `99` comes back. It did before this
    // round too — the per-file table had the same hole for the same reason, and the readings are byte-identical —
    // so this is a *known gap* rather than a behaviour this round introduced. Fixing it means a third state in
    // the layer ("certainly not defined here"), which is worth doing on purpose and with its own measurement.
    assert_eq!(
        with_seed.definition("OBJECT").map(body_of),
        Some("99".to_string()),
        "the unit's `#undef` does not reach the cook's table — see the note above"
    );
    assert!(
        with_seed.definition("_NOBODY_SAYS_").is_none(),
        "and a name nobody defines is nobody's: the seed does not invent one"
    );
}

/// **Does the cook leave a `_STD_BEGIN`/`_STD_END` pair open when two headers use it?** — a probe, not a test.
///
/// ```text
/// cargo test --release -p cpp_code_analysis --test translation_unit a_scope_macro -- --ignored --nocapture
/// ```
///
/// The modules fixture files `std::format` under `std::std::std::std::std::std::std::std::std::std` — ten levels —
/// and the parser's file-boundary rule is not the cause (see `tests/scope_probe.rs`). What is left is the **text**
/// the cook produces: if a scope macro that opens a namespace and closes it again comes out balanced, the nesting
/// cannot be built from one file. This prints the stream and where a second header's declaration ends up.
#[test]
#[ignore = "a probe: prints a cooked stream and a parse tree"]
fn a_scope_macro_two_headers_use() {
    let files = [
        (
            "/p/core.h",
            "#define _STD_BEGIN namespace std {\n#define _STD_END }\n",
        ),
        (
            "/p/a.h",
            "#include \"core.h\"\n_STD_BEGIN\nstruct A { int a; };\n_STD_END\n",
        ),
        (
            "/p/b.h",
            "#include \"core.h\"\n_STD_BEGIN\nstruct B { int b; };\n_STD_END\n",
        ),
        ("/p/main.cpp", "#include \"a.h\"\n#include \"b.h\"\n"),
    ];

    let unit = Unit::new(&files);
    let mut definitions = MacroDefinitions::default();
    let timeline = unit.timeline_of("/p/main.cpp", &mut definitions);
    let shared = timeline.definitions();
    let stitched = timeline.cook_the_unit(&unit.sources, &shared, None, true, None);
    println!("--- cooked ---\n{}--- end ---", stitched.text);
    println!("boundaries: {:?}", stitched.file_boundaries());

    let tree = cpp_parser::CppParser::parse(
        &stitched.text,
        cpp_parser::ParserConfig::default().with_file_boundaries(stitched.file_boundaries()),
    );
    let mut inside: Vec<String> = Vec::new();
    let mut node = tree.get_red_root().descendants().find(|node| {
        &stitched.text[usize::from(node.text_range().start())..usize::from(node.text_range().end())]
            == "B"
    });
    while let Some(current) = node {
        let kind = format!("{:?}", current.kind());
        if kind.contains("Namespace") {
            inside.push(kind);
        }
        node = current.parent();
    }
    println!(
        "namespace ancestors of `B`: {} ({:?})",
        inside.len(),
        inside
    );
    // **And what the index makes of it** — the scope string a fact carries is built by the summary layer from
    // the tree, and a builder that appended each enclosing namespace twice would give the same `std::std::…`
    // shape from a tree with half as many namespaces.
    let configuration = cpp_code_analysis::CompilerConfig::default();
    let indexer = FileIndexer::new(&unit.files, &configuration);
    let indexed =
        indexer.index_unit_rendering(Path::new("/p/main.cpp"), &stitched, SummaryKey::new(0, 0));
    for (path, cooked) in &indexed.files {
        for fact in &cooked.declarations {
            if fact.name.as_str() == "A" || fact.name.as_str() == "B" {
                println!(
                    "{}: {} in scope {:?}",
                    path.display(),
                    fact.name,
                    fact.scope
                );
            }
        }
    }
}

/// **The brace is the file's last token, and the body begins in the next file** — the shape a `boundary > since`
/// comparison misses. A probe, not a test.
#[test]
#[ignore = "a probe: prints where a declaration lands when the `{` ends the file"]
fn a_namespace_whose_brace_ends_the_file() {
    let first = "namespace std {";
    let second = "int b;";
    let text = format!("{first}\n{second}\n");
    let boundary = first.len() + 1;
    let tree = cpp_parser::CppParser::parse(
        &text,
        cpp_parser::ParserConfig::default().with_file_boundaries(vec![boundary]),
    );
    let mut inside: Vec<String> = Vec::new();
    let mut node = tree.get_red_root().descendants().find(|node| {
        &text[usize::from(node.text_range().start())..usize::from(node.text_range().end())] == "b"
    });
    while let Some(current) = node {
        let kind = format!("{:?}", current.kind());
        if kind.contains("Namespace") {
            inside.push(kind);
        }
        node = current.parent();
    }
    println!("boundary {boundary}; namespace ancestors of `b`: {inside:?}");
}