cpp_code_analysis 0.2.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
//! **Semantic checks**: what the analysis can say about a file that is *wrong*, as opposed to what it read.
//!
//! [`crate::FileDiagnostics::errors`] is the parser's answer — the text does not parse — and
//! [`crate::FileDiagnostics::notes`] is what the analysis knows but is not a complaint. This is the third thing a
//! diagnostics channel needs: a construct the grammar accepts and the language does not.
//!
//! # The shape of a check
//!
//! One rule, one file, and one `impl`:
//!
//! ```ignore
//! pub struct Unused;
//!
//! impl Check for Unused {
//!     const CODES: &'static [DiagnosticCode] = &[DiagnosticCode::Unused];
//!
//!     fn check(context: &mut CheckContext<'_>) {
//!         // … and `context.add(code, range, name, message)` is how a finding is reported
//!     }
//! }
//! ```
//!
//! The file's name is the snake-case spelling of the code it reports — `unused.rs` reports `unused`,
//! `param_type_check.rs` reports `param-type-check` — so `grep unused` finds the rule, its tests and its
//! documentation in one pass. [`DiagnosticCode`] is the enum those codes come from, and its `name` is the only
//! place the kebab spelling is written.
//!
//! The shape follows `emmylua_code_analysis`'s `check/checker`: a [`Check`] trait carrying the codes it may report,
//! a [`CheckContext`] that collects findings and filters them through a [`CheckConfig`], and a `run` that is a flat
//! list of typed calls.
//!
//! # A decision comes from the tree; text is for messages
//!
//! The crate has a **lossless tree** and a **lexer**, and every question a check asks has a node or a token for its
//! answer: an access label is a `PublicAccess` node beside a `ClassBody`, a `class` is a `ClassKeyword` token on a
//! `ClassDef`, a declarator is a `Declarator` node, a condition is a `ParenExpr` node. Reaching past those for the
//! text is how this layer produced its first user-visible false positive: `assignment_in_condition` looked for the
//! first `(` and its match **in the text** of an `if`, counted a `<` in `i + 1 < argc` as an opening bracket, ran on
//! into the body, found an `=` in the first statement there, and reported *`=` in a condition is almost always a
//! `==`* on a line whose condition is two comparisons.
//!
//! So:
//!
//! ```text
//!   to decide    walk nodes (`children`, `descendants`) and tokens (`descendants_with_tokens`)
//!   to say       text: the message, and `source[range]` to quote what the reader wrote
//! ```
//!
//! A text comparison is allowed where the token **is** the answer - a keyword token compared against `"class"` has
//! the lexer's boundary around it, which is the whole difference from a substring search. Where a check still reads
//! text, the reason belongs in a comment beside it, and the honest reasons are narrow: a question about *layout*
//! (a directive's own line), or a conservative approximation of a control-flow question that a tree walk over one
//! file cannot answer.
//! # Why `run` is a list of `run_check::<T>` and not a list of closures
//!
//! It was the other shape — `timed(0, &|| …)`, `timed(1, &|| …)` — and the index was the defect: a check's name
//! lived in a second table (`crate::stages`), keyed by the same numbers, so adding a rule meant editing two lists
//! and keeping them in step by hand, with nothing checking that they were. The type carries the name now, the
//! table is gone, and a check that is not in `run` does not exist rather than silently never running.
//!
//! # No timer
//!
//! **The checks are not timed.** They were — a guard per check, with a stage name — and the instrumentation was
//! removed because it does not fit what it measures: diagnostics run on **every keystroke**, so a timer here is a
//! lock, an allocation and a line of output per check per keystroke, paid by every user to answer a question one
//! developer asks once. When the cost of this layer needs measuring, the measurement is a probe
//! (`examples/checks_timing.rs`), which can afford to be intrusive because it runs when somebody asks it to.
//!
//! # The contract: `Known::Yes` or `Known::No`, and nothing else
//!
//! **A check reports only what it knows.** [`Known`](crate::Known) has three values and this layer has two:
//!
//! ```text
//! Known::Yes(_)   the question was answered, and the answer is a problem      -> report
//! Known::No       the question was asked and the answer is a definite no      -> report, for a "not found"
//! Known::Unknown  the question was not answered, for a stated reason          -> report NOTHING
//! ```
//!
//! The third is not a gap in this layer, it is the design of the layer underneath it.
//! [`sema::resolve`](crate::sema::resolve) keeps the two "no"s apart on purpose: `Known::No` means a name is
//! **nowhere**, and [`UnknownReason::NotDeclaredHere`](crate::UnknownReason::NotDeclaredHere) means it is
//! *somewhere else* — usually a header the analysis has not read. The first is a fact about the file; the second
//! is a fact about us.
//!
//! # Why a check that reports nothing is the ordinary case, and why that is the point
//!
//! The failure mode this layer has to avoid is not missing a problem, it is **inventing one**, because an editor
//! that underlines correct code is one the user turns off — and then it reports nothing at all, forever. The
//! measurement that keeps it honest is a corpus that is *known good*: the standard library. A check that reports
//! anything at all on a header it read correctly is wrong, and that is a test that can fail.

use std::path::Path;

use cpp_parser::SourceRange;

use crate::file::view::FileView;
use crate::{FileSummary, ProjectIndex};

pub mod access_invisible;
pub mod argument_count;
pub mod assign_type_check;
pub mod assignment_in_condition;
// pub mod assign_type_check;
pub mod config;
pub mod diagnostic_code;
// **Being ported to the Check trait**: git mv'd to their new names, still written against the old
// Checks/Finding { check: … } shape, so they are declared again the moment their bodies are rewritten. Kept in
// the tree rather than deleted, because their reasoning (and the measured 119-findings defect they record) is what
// the ported versions have to preserve.
mod borrowed;
mod braces_around_statements;
pub mod concept_not_satisfied;
mod cstyle_cast;
mod dangling_field;
mod dangling_return;
mod else_after_return;
mod implicit_bool_conversion;
pub mod include_not_found;
mod macro_parentheses;
pub mod macro_redefined;
mod missing_include;
pub mod missing_return;
pub mod param_type_check;
pub mod redefinition;
pub mod return_type_mismatch;
mod simplify_boolean_expr;
pub mod syntax_error;
mod ue_generate_body;
mod ue_generated_header;
mod ue_macro_scope;
mod ue_naming;
mod ue_specifier;
pub mod undefined_field;
pub mod undefined_name;
pub mod unnecessary_branch;
mod unreal;
pub mod unused;
mod use_after_free;
mod use_auto;
mod use_nullptr;
mod use_override;

pub use config::CheckConfig;
pub use diagnostic_code::{DiagnosticCode, RuleSeverity, RuleTag};

/// **What a check found**, in the form a diagnostics channel shows it.
///
/// A `Finding` is a *claim about a place in a file*, so it carries the span, the code and the sentence together: a
/// consumer that had to assemble the message from the parts would be a second author of it, and the two would
/// drift. The check that knows why it fired is the one that says so.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Finding {
    /// The span to underline — the whole construct, not just its first token.
    pub range: SourceRange,
    /// The name the finding is about, as the file spells it. Empty when the finding is not about one name.
    pub name: String,
    /// **Which rule reported it** — the enum, not a string: see [`DiagnosticCode`].
    pub code: DiagnosticCode,
    /// The sentence shown to the user. Written by the check, because the check is what knows.
    pub message: String,
}

/// **A check**: one rule, and the codes it may report.
///
/// `CODES` is what makes a whole check skippable: [`run_check`] does not call one whose every code is off, which is
/// the only skip that saves the walk rather than the message.
pub trait Check {
    /// The codes this check can report — see [`CheckConfig::is_enabled`].
    const CODES: &'static [DiagnosticCode];

    /// **The rule.** Report through [`CheckContext::add`], which is also where a disabled code is dropped.
    fn check(context: &mut CheckContext<'_>);
}

/// **Run one check, unless every code it reports is turned off.**
///
/// The skip is here rather than inside each check because the expensive part of a check is the walk over the tree,
/// not the sentence it produces: a rule the user turned off should cost nothing at all.
pub fn run_check<T: Check>(context: &mut CheckContext<'_>) {
    // **A C++-only rule costs nothing in a C file.** The filter below is the same answer one level up: a check whose
    // every code is C++-only is not a question about this file at all, so it is skipped before it walks the tree. A
    // check that reports both kinds still runs, and the per-finding filter drops the half that does not apply.
    if context.is_c() && T::CODES.iter().all(|code| code.is_cpp_only()) {
        return;
    }
    // **An Unreal rule costs nothing outside Unreal.** The project says whether it is engine code — see
    // `[unreal] enable` — and a rule that does not know is skipped before it walks anything.
    if !context.unreal && T::CODES.iter().all(|code| code.is_unreal_only()) {
        return;
    }
    if T::CODES.iter().any(|code| context.config.is_enabled(*code)) {
        T::check(context);
    }
}

/// **Everything a check is given, and where it puts what it found.**
///
/// Deliberately *not* a [`Session`](crate::Session). A check that could ask the session anything would eventually
/// ask it to parse something, and a diagnostics channel whose cost is "one parse per check per keystroke" is a
/// channel that gets removed. What is here is a view of **one file** and the index as it stands.
pub struct CheckContext<'a> {
    /// The file being checked, as the index spells it — the key to every answer below.
    pub path: &'a Path,
    /// The file's summary: the facts its own text produced. A check that needs only this is a check that cannot be
    /// wrong about another file.
    pub summary: &'a FileSummary,
    /// **The file's questions, and the only way a check asks them.**
    pub model: crate::sema::model::SemanticModel<'a>,
    /// **The text a range from the *tree* is an offset into** — the view's own reading, which is the **rendering**:
    /// macros expanded, directives resolved, headers inlined where their `#include` was.
    ///
    /// Settled by reading [`Session::view`](crate::Session::view) rather than by experiment, after a test of mine
    /// concluded the opposite from a fixture whose include had silently failed: its first line is *"The rendering, or
    /// a request for it — **never the file's own tokens**"*. A rendering is a unit walk, a preprocess and a render —
    /// 65–190 ms for a standard-library header, and megabytes of text — which is why it is built on request and why
    /// [`CheckContext::own_syntax_nodes`] prunes what it produces.
    ///
    /// So this text is **not** the file the reader is looking at; that one is [`CheckContext::written`].
    pub source: &'a str,
    /// **The text a range from the *summary* is an offset into** — the file as the reader wrote it.
    ///
    /// Two texts, because this layer reads ranges from two places and they are in two coordinate systems:
    ///
    /// ```text
    ///   a range from `context.tree()`     -> context.source    the rendering
    ///   a range from `context.summary`    -> context.written   the file
    /// ```
    ///
    /// Measured, and it is what this field was added for: `macro_redefined` compared two `#define` bodies through
    /// the *rendering* while the ranges came from the summary — so it read a fragment of the expanded function
    /// against nothing at all, and reported a macro as a redefinition of itself.
    ///
    /// What a finding is *published in* is the file's coordinates, because the server places a range with the VFS
    /// line index. That crossing belongs where a finding is added — see [`CheckContext::add`].
    pub written: &'a str,
    /// **The parse errors of the reading this run is about**, which is what the `syntax-error` check publishes.
    ///
    /// Passed in rather than asked for: the errors belong to the **tree**, and this context deliberately holds a
    /// *model* over it — a check that could reach the tree would be a check that could re-parse.
    pub errors: &'a [cpp_parser::CppParseError],
    /// **The view this run is about**, which is what turns a range from the tree into a range in the file.
    ///
    /// Held for that one crossing and nothing else: a check that reached through it could parse, which is the
    /// thing [`CheckContext`]'s own documentation says this layer must not be able to do.
    pub view: &'a FileView,
    /// Which codes may be reported — see [`CheckConfig`].
    pub config: CheckConfig,
    /// **The language this file is compiled as** — `-std=c++17`, `-std=gnu89`, or "not told".
    ///
    /// A rule is not always a rule in both languages: a C program has no `static_cast`, so a C-style cast is the only cast
    /// there is and [the rule that flags one](super::cstyle_cast) must not fire. `family()` answers `None` when the
    /// configuration enables both families, which is the honest answer for a parse nobody configured.
    pub language: cpp_parser::features::LanguageConfig,
    /// **Is this project Unreal Engine code?** — the switch that makes the two engine rules run, and the reason they
    /// are not on for an ordinary C++ project: `class Widget` would be reported as a missing `A`/`U`/`F` prefix.
    pub unreal: bool,
    /// **The directories whose files this project may add an `#include` for** — the workspace root, and (once libraries
    /// exist) each library's own path.
    ///
    /// A check that proposes an edit *into another file's existence* must know which files are the project's: a
    /// toolchain header, a module unit read for `import std;` and a vendored tree outside the workspace are all in the
    /// index, and none of them may be suggested — see [`super::missing_include`].
    pub inside: &'a [std::path::PathBuf],
    findings: Vec<Finding>,
}

impl<'a> CheckContext<'a> {
    /// A context for one file — the session builds these; a test builds one to ask about a fixture.
    pub fn new(
        path: &'a Path,
        summary: &'a FileSummary,
        model: crate::sema::model::SemanticModel<'a>,
        source: &'a str,
        written: &'a str,
        errors: &'a [cpp_parser::CppParseError],
        view: &'a FileView,
        config: CheckConfig,
        language: cpp_parser::features::LanguageConfig,
        unreal: bool,
        inside: &'a [std::path::PathBuf],
    ) -> Self {
        CheckContext {
            path,
            summary,
            model,
            source,
            written,
            errors,
            config,
            view,
            language,
            unreal,
            inside,
            findings: Vec::new(),
        }
    }

    /// **Report a finding whose range is in the *tree*.**
    ///
    /// The ordinary entry point, because most checks read the tree — and the range they have is therefore in the
    /// **rendering**, which is not the text a client is showing. The crossing happens here: see
    /// [`CheckContext::in_the_file`], and use [`CheckContext::add_in_the_file`] for a finding whose range already
    /// came from the summary.
    ///
    /// A check says what it found and does not ask whether anyone wants to hear it: the filter belongs here because
    /// there are eleven checks and the twelfth would forget. This is also where a per-line suppression will go (a
    /// comment naming a code on the line the finding is on), for the same reason — one place, so that no check has
    /// to know it was suppressed.
    pub fn add(
        &mut self,
        code: DiagnosticCode,
        range: SourceRange,
        name: impl Into<String>,
        message: impl Into<String>,
    ) {
        let in_the_reading = range;
        let range = self.in_the_file(range);
        self.push(code, range, Some(in_the_reading), name, message);
    }

    /// **Report a finding whose range is already in the file** — for the checks that read the *summary*, whose
    /// every range is a file offset (see [`CheckContext::written`]).
    ///
    /// A second method rather than a flag, because the difference is which text the range came from and a check
    /// that got it wrong would put a squiggle on another line rather than fail to compile.
    pub fn add_in_the_file(
        &mut self,
        code: DiagnosticCode,
        range: SourceRange,
        name: impl Into<String>,
        message: impl Into<String>,
    ) {
        self.push(code, range, None, name, message);
    }

    /// **A node's text, as a slice of the rendering** — no `SyntaxText`, no `String`, no `trim`.
    ///
    /// `node.text()` builds a `SyntaxText` and `.to_string()` copies it; a check that asks for the text of hundreds of nodes
    /// per file pays that copy for each. The source the node's range came from is right here, so the answer is a slice.
    ///
    /// **No `trim`.** A *token* never carries surrounding whitespace, and a node from this tree carries only what the cook
    /// put between its tokens — which is the text a reader wrote, not padding a caller has to strip. The first version of
    /// these checks trimmed anyway, which was a habit from reading file text rather than a need.
    pub fn node_text(&self, node: &cpp_parser::CppSyntaxNode) -> &'a str {
        let range = cpp_parser::source_range(node.text_range());
        self.source
            .get(range.start_offset..range.end_offset())
            .unwrap_or_default()
    }

    /// **Is this file compiled as C?** — the question a rule that only makes sense for C++ asks before it fires.
    ///
    /// `None` (a configuration that enables both families) answers `false`: a rule is quiet when it *knows* the language is
    /// C, not when it cannot tell, so an unconfigured project keeps the findings it had.
    pub fn is_c(&self) -> bool {
        self.language.family() == Some(cpp_parser::features::Family::C)
    }

    /// **The comment and literal ranges of the file as written**, for the rules that read the *text* rather than the tree.
    ///
    /// A rule that scans `written` — `cstyle_cast`, `use_auto` — is scanning prose and data as well as code, and the
    /// spellings it looks for occur in both: a comment that says "we removed `(int)` casts" and a string that contains
    /// `"NULL"` are not a cast and a null pointer. The reading has this for free (the cook strips comments), the written
    /// text does not, so the check layer lexes once and hands the ranges over.
    ///
    /// **One lex per call**, not per offset: the two rules that need it call this once and test every candidate against the
    /// list. A lex is not a parse — it is the `skip_trivia` the parser already does — and two per file per run is not the
    /// cost this layer is written against.
    pub fn comments_and_literals(&self) -> Vec<SourceRange> {
        let (tokens, _) = cpp_parser::lex(self.written, &cpp_parser::LexerConfig::default());
        tokens
            .into_iter()
            .filter(|token| {
                matches!(
                    token.kind,
                    cpp_parser::CppTokenKind::LineComment
                        | cpp_parser::CppTokenKind::BlockComment
                        | cpp_parser::CppTokenKind::StringLiteral
                        | cpp_parser::CppTokenKind::CharLiteral
                )
            })
            .map(|token| token.range)
            .collect()
    }

    /// Is this file offset inside a comment or a literal?
    pub fn in_a_comment_or_literal(&self, offset: usize, protected: &[SourceRange]) -> bool {
        protected
            .iter()
            .any(|range| offset >= range.start_offset && offset < range.end_offset())
    }

    /// **A range read from the tree, said in the file's coordinates.**
    ///
    /// The outbound half of the crossing this crate makes everywhere else: a range in the rendering is an offset
    /// into text the cook produced — macros expanded, a header inlined, a directive resolved away — and a client is
    /// showing the **file**. `file_offset_of` maps both ends, and a token a macro produced reports *where the macro
    /// was invoked*, which is the place the reader can see.
    ///
    /// An end that cannot be placed keeps the start, so a half-mappable range is a short one rather than a lost
    /// finding; a **start** that cannot be placed leaves the range alone, which is the only honest thing left to do
    /// and is also what the checks did before this crossing existed. Measured before it did: on a file with a
    /// header inlined, `unused`'s finding for a local after the `#include` was published **on the line the header
    /// occupied** — the same offset in a shorter text.
    fn in_the_file(&self, range: SourceRange) -> SourceRange {
        let Some(start) = self
            .view
            .file_offset_of(crate::file::coordinates::ReadingOffset::new(
                range.start_offset,
            ))
        else {
            return range;
        };
        // **The end is a different question from the start** - see `FileView::file_offset_of_end`: asking
        // `file_offset_of` about an end that falls in whitespace walks forward to the next token, which is how a
        // finding about the value `123` came out covering the rest of the line. Measured on the user's own code:
        // `std::string x = 123;` underlined from `123` to the end of the statement.
        let end = self
            .view
            .file_offset_of_end(crate::file::coordinates::ReadingOffset::new(
                range.end_offset(),
            ))
            .unwrap_or(start);
        SourceRange::new(start.get(), end.get().saturating_sub(start.get()))
    }

    /// The one place a finding becomes a [`Finding`] — see [`CheckContext::add`].
    fn push(
        &mut self,
        code: DiagnosticCode,
        range: SourceRange,
        in_the_reading: Option<SourceRange>,
        name: impl Into<String>,
        message: impl Into<String>,
    ) {
        if !self.config.is_enabled(code) {
            return;
        }

        // **A C++-only rule says nothing about a C file** — see [`DiagnosticCode::is_cpp_only`]. The skip in
        // [`run_check`] covers a check that is entirely C++, and this covers the codes of a check that reports both.
        if self.is_c() && code.is_cpp_only() {
            return;
        }

        // **A finding has to be about this file's own text.** A rendering has a header inlined where its `#include`
        // was, so a node a check finds may belong to **another file** — and its range, mapped back through the span
        // table, lands on the `#include` line. That is the coordinate defect a reader sees as a diagnostic drawn
        // over the wrong line, and the cook already answers the question per token: `RenderedSpan::written` is `None`
        // exactly where the text came from somewhere else. Asking it here is the same lesson as the AST layer — the
        // machinery existed, and this layer was re-deriving a worse version of it by comparing texts.
        if let Some(in_the_reading) = in_the_reading
            && !self.view.was_written_here(in_the_reading)
        {
            return;
        }
        self.findings.push(Finding {
            range,
            name: name.into(),
            code,
            message: message.into(),
        });
    }

    /// **The file's tree** — through the model, which is the only place it lives.
    pub fn tree(&self) -> &cpp_parser::CppSyntaxNode {
        self.model.tree()
    }

    /// **The scopes of the file's own text**, which is what turns a name in an expression into a declaration.
    pub fn scopes(&self) -> &crate::ScopeTree {
        self.model.scopes()
    }

    /// The index as it stands. Answers about *other* files are answers about whatever was indexed — which is why a
    /// check may only report a definite `Known::No`, and never an absence of an answer.
    pub fn index(&self) -> &ProjectIndex {
        self.model.index()
    }

    /// **The typed root of this file's tree** — where every check should start.
    ///
    /// The crate has a typed AST (`CppTranslationUnit`, `CppIfStat`, `CppClassDef`, `CppParamList`, …) and this
    /// layer was written without it: every check compared `CppSyntaxKind`s and re-implemented, by hand, the
    /// accessors the typed layer already has. The cost is not only verbosity - a hand-written kind comparison is a
    /// decision made by the check about a shape the parser owns, and when the shape moves the check goes quiet
    /// (measured twice: `int f() { }` is not a `FunctionDef`, and `struct` is a `StructDef` rather than a
    /// `ClassDef`) instead of failing to compile.
    ///
    /// The cast is cheap - the rowan node is handed back, not rebuilt - and `None` only for a tree that is not a
    /// translation unit, which is a state this analysis cannot be handed.
    pub fn root(&self) -> Option<cpp_parser::CppTranslationUnit> {
        // The trait has to be in scope for `cast`, which is where the typed layer puts it.
        use cpp_parser::CppAstNode;
        cpp_parser::CppTranslationUnit::cast(self.tree().clone())
    }
    /// **The type of an expression** — the model's, remembered per node for as long as this request lasts.
    pub fn type_of(
        &self,
        expression: &cpp_parser::CppSyntaxNode,
    ) -> crate::Known<(crate::sema::types::Type, std::path::PathBuf)> {
        self.model.type_of(expression)
    }

    /// **Every node of this file's own text** — the one traversal a check should walk.
    ///
    /// It exists because `self.tree().descendants()`, which is what every check in this layer used, is the wrong
    /// question twice over:
    ///
    /// ```text
    ///   the scope     the tree is a **rendering** — see `CheckContext::source` — so a full walk visits every node
    ///                 of every inlined header, and a node from another file is not a fact about this one. In a
    ///                 rendering the inlined text arrives as **top-level children** of the translation unit, and the
    ///                 cook marks exactly that per token (`RenderedSpan::written`), so pruning the children that were
    ///                 not written here removes a whole header for the cost of one question per child
    ///   the shape     a walk that compares `CppSyntaxKind` by hand is this layer guessing at a shape the parser owns
    ///                 — see `CheckContext::own`, which asks the typed layer instead
    /// ```
    ///
    /// Both are answered by the same observation: in a rendering, the text of an inlined header is spliced in where
    /// the directive was, so it arrives as **top-level children** of the translation unit. The cook marks exactly
    /// that per token (`RenderedSpan::written`), so pruning the children that were not written here removes the whole
    /// header at the cost of one question per child — and everything below a kept child is this file's own text.
    ///
    /// (A child that is only *partly* this file's — a declaration whose first tokens come from a macro defined
    /// elsewhere — is pruned whole, which is the safe direction: not reporting is a missed finding, reporting on
    /// another file's text is a wrong one.)
    /// **The top-level pieces of this file's own text** — what the two iterators below are built on.
    ///
    /// Kept separate because a token walk has to start here and not from every node: taking
    /// `descendants_with_tokens()` of each node of a tree yields every token once per ancestor, which inflated
    /// `unused`'s spelling counts until the rule never fired — measured, two of its tests went red.
    fn own_top_level_nodes(&self) -> Vec<cpp_parser::CppSyntaxNode> {
        let root = self.tree().clone();
        let mut kept = Vec::new();
        for child in root.children() {
            let range = cpp_parser::source_range(child.text_range());
            if self.view.was_written_here(range) {
                kept.push(child);
            }
        }
        kept
    }

    /// **Every node of this file's own text**, once each, in document order.
    /// **Every node of this file's own text**, once each, in document order.
    ///
    /// # The `once(child)` that made every declaration count twice
    ///
    /// This used to be `once(child.clone()).chain(child.descendants())`, and `descendants()` **already includes the
    /// node it is called on** — so every top-level child was yielded twice. Measured on `int unfinished() { }`, which
    /// holds one declaration: `own_syntax_nodes()` counted **9** where `descendants()` is 8, and the function
    /// definition list held the same `Declaration 0..20` at index 0 *and* index 1.
    ///
    /// What it cost depends on the check, which is why it went unnoticed. A check that filters for a **kind below** a
    /// declaration — every statement walk, every expression walk — never saw it, because a `Declaration` is not the
    /// thing it asks for. The two that ask about *declarations themselves* reported every finding **twice**:
    /// measured, `missing-return` gave two identical findings for `int unfinished() { }`. A duplicate that only
    /// surfaces on the one node type nothing else looks at.
    pub fn own_syntax_nodes(&self) -> impl Iterator<Item = cpp_parser::CppSyntaxNode> + '_ {
        self.own_top_level_nodes()
            .into_iter()
            .flat_map(|child| child.descendants())
    }

    /// **Every node of this file's own text, of one type** — what a check actually asks for.
    ///
    /// ```ignore
    ///   for statement in context.own::<CppIfStat>() { … }         // not: filter(|node| CppSyntaxKind::from(…))
    /// ```
    ///
    /// The typed layer is what makes this possible: `CppAstNode::cast` is the parser's own answer to "is this node
    /// that", and a check that asks it cannot be wrong about a shape the parser owns. The hand-written kind
    /// comparisons this replaces went quiet twice — a definition is not a `FunctionDef`, and `struct` is a
    /// `StructDef` — while compiling and looking correct.
    pub fn own<T: cpp_parser::CppAstNode + 'static>(&self) -> impl Iterator<Item = T> + '_ {
        self.own_syntax_nodes().filter_map(T::cast)
    }

    /// **Every member access in this file's own text** — `a.b`, `a->b`, by the definition the sema layer owns.
    ///
    /// The definition is [`crate::sema::resolve::member_access_of`] and not a node kind, because the two disagree
    /// and the sema layer is the one that is right: measured with `cpp_dump`, `w.secret` parses as
    ///
    /// ```text
    ///   Syntax(IndexExpr)
    ///     Syntax(IdentifierExpr) "w"    Token(Dot) "."    Token(Identifier) "secret"
    /// ```
    ///
    /// — an **`IndexExpr`**, exactly as `arr[0]` is, which is what `member_access_of` says in its own documentation
    /// (*"`arr[0]` is the same node kind with brackets instead of a dot"*). The typed layer's `CppMemberExpr` accepts
    /// `MemberExpr | ArrowExpr`, kinds this grammar does not appear to produce for a dot, so a check filtering on it
    /// finds **nothing at all** — measured: `access_invisible` counted 38 own nodes and **0** member expressions, and
    /// `undefined-field` has been blind to `.` for as long as it has existed.
    ///
    /// The kinds are still used as a cheap filter before the shape is read, so the cost is one kind test per node
    /// rather than a child list per node — `CppIndexExpr`/`CppMemberExpr` would be two casts per node, and this is
    /// the hot path of four checks.
    pub fn member_accesses(
        &self,
    ) -> Vec<(
        cpp_parser::CppSyntaxNode,
        crate::sema::resolve::MemberAccess,
    )> {
        use cpp_parser::CppSyntaxKind;
        self.own_syntax_nodes()
            .filter(|node| {
                matches!(
                    // **The kind here is a filter over *shapes*, not a claim about what a node means** — the claim
                    // is `member_access_of`'s, and it reads the operator to make it. That distinction is what makes
                    // this use legitimate: `.` arrives as `IndexExpr`, which the typed layer would call an index.
                    CppSyntaxKind::from(node.kind()),
                    CppSyntaxKind::IndexExpr | CppSyntaxKind::MemberExpr | CppSyntaxKind::ArrowExpr
                )
            })
            .filter_map(|node| {
                crate::sema::resolve::member_access_of(&node).map(|access| (node, access))
            })
            .collect()
    }

    /// **Every token of this file's own text, once each** — for the checks that count spellings rather than read
    /// structure.
    ///
    /// Pruned the same way as [`CheckContext::own_syntax_nodes`] and for the same reason: a token inside an inlined
    /// header is another file's spelling, and counting it would make `unused` answer about a name in `<string>`.
    pub fn own_tokens(&self) -> impl Iterator<Item = cpp_parser::CppTokenData> + '_ {
        self.own_top_level_nodes()
            .into_iter()
            .flat_map(|child| child.descendants_with_tokens().collect::<Vec<_>>())
            .filter_map(|element| element.into_token())
            .map(|token| cpp_parser::CppTokenData {
                kind: token.kind().into(),
                range: cpp_parser::source_range(token.text_range()),
            })
    }

    /// Take the findings, sorted the way a list reads — see [`run`].
    fn into_findings(mut self) -> Vec<Finding> {
        // **Sorted by position**, because the order the checks happen to be listed in is an implementation detail
        // and a diagnostics list sorted by it is a list that reshuffles when a check is added. Two findings at the
        // same offset keep the order they were produced in, which is the order of `run` — deliberate, so that the
        // more specific check is written first and reads first.
        self.findings
            .sort_by_key(|finding| (finding.range.start_offset, finding.range.length));
        self.findings
    }
}

// **Every function *definition* in this file** - a node with both a parameter list and a body.
//
// Recognised by **shape** rather than by node kind, and that is not tidiness: measured, `int count() { }` at file
// scope is **not** a `FunctionDef` in this grammar - the dump shows a `NameExpr`, a `ParameterList` and a
// `CompoundStat` with no function node around them - so every check that filtered on that kind reported nothing,
// on every file, while looking correct. A definition is what has a parameter list and a body; which node the
// grammar wrapped them in is its business.

/// **The condition of an `if`/`while`/`switch`, taken from the node and never from its text.**
///
/// A node's child is what the parser decided the condition is. This was a text scan in two checks at once - the
/// first `(` and its match - and counting parentheses through text means deciding what a `<` is, which is how a
/// condition holding `i + 1 < argc` was read past its own `)` and into the body.
pub fn condition_of(statement: &cpp_parser::CppSyntaxNode) -> Option<cpp_parser::CppSyntaxNode> {
    // **The typed layer's node for a parenthesised condition**, rather than "the first child that is not the body":
    // `CppParenExpr` is the parser's own answer, and `a < b` inside it cannot be mistaken for a bracket.
    use cpp_parser::CppAstNode;
    cpp_parser::CppParenExpr::cast(statement.clone())
        .is_some()
        .then(|| statement.clone())
        .or_else(|| {
            statement
                .children()
                .find_map(|child| cpp_parser::CppParenExpr::cast(child).map(|p| p.syntax().clone()))
        })
}

/// **The one word a condition is, when it is a bare literal** — `true`, `false`.
///
/// Decided from the **tokens**, through the typed layer's own vocabulary: the parentheses and the whitespace are
/// dropped by kind, and what is left has to be exactly one token that is the keyword. A string literal is a
/// different kind, so `if ("true")` cannot be read as the keyword.
///
/// The kind comes out as `CppTokenKind::from(CppKind::from(token.kind()))`, and the shape of that expression is the
/// point: this crate's rowan kind is [`CppKind`], the wrapper around `Node(CppSyntaxKind)` and `Token(CppTokenKind)`,
/// so a token's kind is only usable once unwrapped. `examples/token_kinds.rs` prints both halves for any source,
/// which is how a round spent believing the wrong thing about this API was settled.
pub fn literal_condition_of(condition: &cpp_parser::CppSyntaxNode) -> Option<String> {
    use cpp_parser::CppTokenKind;

    let mut words = Vec::new();
    for token in condition
        .descendants_with_tokens()
        .filter_map(|element| element.into_token())
    {
        match CppTokenKind::from(token.kind()) {
            CppTokenKind::LeftParen
            | CppTokenKind::RightParen
            | CppTokenKind::Whitespace
            | CppTokenKind::Newline => {}
            CppTokenKind::TrueKeyword => words.push("true".to_string()),
            CppTokenKind::FalseKeyword => words.push("false".to_string()),
            // Anything else — a name, a literal, an operator — means the condition is not a bare literal.
            _ => return None,
        }
    }

    match words.as_slice() {
        [word] => Some(word.clone()),
        _ => None,
    }
}
/// **Is this node a class-like *definition*?** — `class`, `struct` or `union`.
///
/// Delegated to the typed layer, which already answers exactly this: `CppClassDef::can_cast` accepts `ClassDef`,
/// `StructDef` **and** `UnionDef`, and it carries `get_name_text`, `is_struct` and `is_union` with it.
///
/// This function used to compare `CppSyntaxKind::ClassDef` by hand, which is the defect the whole round is about: it
/// worked on every `class` and on **no `struct` at all** — and `struct` is what `std::string` and the user's own
/// types are. Measured with `cpp_dump`: `struct MyString { … }` is a **`StructDef`**. The typed layer had known that
/// all along; this layer was re-deriving a worse answer from a node kind.
pub fn is_a_class_definition(node: &cpp_parser::CppSyntaxNode) -> bool {
    use cpp_parser::CppAstNode;
    cpp_parser::CppClassDef::cast(node.clone()).is_some()
}

/// **Is this node a function definition?** See [`function_definitions`] for why the question is about shape.
pub fn is_a_function_definition(node: &cpp_parser::CppSyntaxNode) -> bool {
    use cpp_parser::{CppAstNode, CppCompoundStat, CppDeclaration};

    // **The body is a direct child and the parameters are not**, which is the asymmetry that made this predicate
    // wrong the first time and silent for three checks: measured, `int count() { }` is a `Declaration` whose
    // `CompoundStat` is a child while its `ParameterList` is a grandchild, inside `InitDeclarator > Declarator`. The
    // predicate is now written with the typed layer, where that asymmetry is the difference between `children` and
    // `descendants` rather than a fact a reader has to remember.
    let Some(declaration) = CppDeclaration::cast(node.clone()) else {
        return false;
    };
    let Some(body) = declaration.children::<CppCompoundStat>().next() else {
        return false;
    };
    let body = span_of(body.syntax());

    // **The parameters must belong to THIS declaration's declarator, not to anything inside it.**
    //
    // The version before asked only whether *some* parameter list in this node began before the body — and a class
    // definition satisfies that: measured, `struct S { ~S() {} };` is a `Declaration` whose `DeclSpecifierSeq` holds
    // the `StructDef`, so its `CompoundStat` child is **the class body** and a method's parameter list begins before
    // it. Every class with a defined member was therefore a "function definition", and the checks that ask this
    // question reported the class itself. Measured through `ctor_probe`: `struct S { ~S() {} };` at namespace scope
    // came out as a definition whose return type was the whole `struct S { … }` text.
    //
    // Anchoring on the declaration's **own** `InitDeclarator` is what makes the parameters the ones the body belongs
    // to. A definition has exactly one: `int f() { }` and `S::S() { }` each put their `()` inside it.
    let Some(parameters) =
        function_parameters(declaration.syntax()).map(|parameters| span_of(parameters.syntax()))
    else {
        return false;
    };

    // The list is inside the head, so it starts before the body; and the body is not inside the list, which is what
    // `void f(int g(void))` would otherwise look like — a list inside a list.
    !contains(parameters, body) && parameters.0 < body.0
}

/// **The parameter list a function declaration writes**, without walking its body.
///
/// `CppDeclaration::get_param_list` is the declarator's own list — a function's body belongs to the declaration, so
/// `descendants()` reached every lambda in it and answered *their* lists as well as this one's (measured: a function with a
/// lambda answered two parameters). The walk of the whole body was also the cost: three checks ask this per function.
///
/// A node that is not a declaration keeps the typed descendant walk, which is what a caller handing in a lambda's body needs.
fn function_parameters(function: &cpp_parser::CppSyntaxNode) -> Option<cpp_parser::CppParamList> {
    use cpp_parser::{CppAstNode, CppDeclaration, CppLambdaExpr, CppParamList};
    if let Some(declaration) = CppDeclaration::cast(function.clone()) {
        return declaration.get_param_list();
    }
    if let Some(lambda) = CppLambdaExpr::cast(function.clone()) {
        return lambda.get_params();
    }
    cpp_parser::typed_descendants::<CppParamList>(function).next()
}

/// **The `return`s a function's body holds**, without the ones a nested lambda owns.
///
/// A closure's result type is deduced from its own `return`s, so a rule judging *this* function's return type must not read them —
/// and `descendants()` has no way to skip a subtree. The walk stops at a `CppLambdaExpr`.
pub fn the_returns_in(function: &cpp_parser::CppSyntaxNode) -> Vec<cpp_parser::CppReturnStat> {
    use cpp_parser::CppAstNode;
    let mut found = Vec::new();
    let body = cpp_parser::CppDeclaration::cast(function.clone())
        .and_then(|declaration| declaration.get_body());
    if let Some(body) = body {
        collect_returns(body.syntax(), &mut found);
    }
    found
}

fn collect_returns(node: &cpp_parser::CppSyntaxNode, found: &mut Vec<cpp_parser::CppReturnStat>) {
    use cpp_parser::CppAstNode;
    if let Some(returned) = cpp_parser::CppReturnStat::cast(node.clone()) {
        found.push(returned);
        return;
    }
    for child in node.children() {
        if cpp_parser::CppLambdaExpr::can_cast(child.kind().into()) {
            continue;
        }
        collect_returns(&child, found);
    }
}

/// A node's span as `(start, end)` offsets — what the rest of this layer compares, and cheap to pass around.
fn span_of(node: &cpp_parser::CppSyntaxNode) -> (usize, usize) {
    let range = node.text_range();
    (usize::from(range.start()), usize::from(range.end()))
}

/// Does `outer` contain `inner`? Both are `(start, end)` in the same text's offsets.
fn contains(outer: (usize, usize), inner: (usize, usize)) -> bool {
    outer.0 <= inner.0 && outer.1 >= inner.1
}

/// **The body of a function definition**, when it has one.
///
/// Asked of the typed layer: a body is a `CppCompoundStat`, and where the parser put it is the parser's business —
/// which is the lesson of the two defects this layer has already had from hand-rolled shape tests.
pub fn body_of(function: &cpp_parser::CppSyntaxNode) -> Option<cpp_parser::CppSyntaxNode> {
    use cpp_parser::{CppAstNode, CppCompoundStat, CppDeclaration};
    CppDeclaration::cast(function.clone())?
        .children::<CppCompoundStat>()
        .next()
        .map(|body| body.syntax().clone())
}
/// **Every function *definition* in this file's own text.**
///
/// ```text
///   reported by  missing-return, param-type-check, return-type-mismatch
/// ```
///
/// It walks [`CheckContext::own_syntax_nodes`] — this file's own text, with the inlined headers pruned — and asks
/// [`is_a_function_definition`], which is the **one** place that question is answered.
///
/// It used to answer it here as well, with a second copy of the shape test that asked for the parameter list *and*
/// the body to be direct children. That copy was the broken one, the predicate beside it had already been fixed, and
/// the three checks that call this function therefore reported nothing on any file while looking correct — measured,
/// and the reason their positive tests were still ignored.
pub fn function_definitions(context: &CheckContext<'_>) -> Vec<cpp_parser::CppSyntaxNode> {
    use cpp_parser::CppAstNode;

    // **Declarations first, then the shape question.** Only a `Declaration` can define a function, and asking the predicate of
    // every node in the file — names, literals, specifiers — is what this walk did: the predicate casts to a declaration and
    // returns `false` for all of them.
    context
        .own::<cpp_parser::CppDeclaration>()
        .map(|declaration| declaration.syntax().clone())
        .filter(is_a_function_definition)
        .collect()
}
/// **The return type a function definition writes**, as the text before its name.
///
/// Read as **text** rather than as nodes, because the recovery the grammar performs around a declarator is what
/// makes a node-shaped answer unreliable here: `int* f()`, `const std::string& f()` and `auto f()` each have to come
/// out as the spelling the reader wrote.
///
/// `None` for a definition with nothing before its name — a constructor — and for a head this cannot read.
/// **The specifier keywords that are not a return type.**
///
/// A declaration's specifier sequence holds the *declaration specifiers* — and several of them say how a function is
/// built rather than what it returns. `static int f()` puts `static` in that sequence, `constexpr ~S()` puts
/// `constexpr` there and **no type at all**, and both were being read out as the return type:
///
/// ```text
///   constexpr ~S() {}                return_type_written_by -> Some("constexpr")   should be None
///   static int f() {}                return_type_written_by -> Some("static int")  should be "int"
///   virtual int f() {}               return_type_written_by -> Some("virtual int") should be "int"
///   explicit S(int a) {}             return_type_written_by -> Some("explicit S")  should be None
/// ```
///
/// A list of spellings is the **weakest** form this rule can take, and it is chosen deliberately: the specifier
/// sequence is read as text (see [`return_type_written_by`] for why), and the alternative — a second reader of the
/// same sequence that decides by token kind — is the defect this whole function exists to remove. The list is
/// C++'s own set of decl-specifiers that cannot be part of a type, and a spelling that is missing from it shows up as
/// a wrong message rather than as a wrong finding, which is the direction to be wrong in.
const NOT_A_TYPE: &[&str] = &[
    "constexpr",
    "consteval",
    "constinit",
    "static",
    "inline",
    "virtual",
    "explicit",
    "friend",
    "extern",
    "mutable",
    "register",
    "thread_local",
    "typedef",
];

/// **The three parts of a function's head, read once**: what it returns, what it is called, and where that name is.
///
/// One function rather than three, because the three are answers about **one** span of text and three readers of it
/// disagreed — each in its own way, and each silently:
///
/// ```text
///   return_type_written_by read the whole head as the type   -> "explicit S", "int S::f", "static int"
///   name_declared_by       read the last child ending before
///                          the parameter list                 -> None for every definition
///   range_of_the_name      compared a node kind that does not exist -> None for every function
/// ```
///
/// Splitting the head once means a constructor cannot be given a return type by one reader while another reader
/// fails to see it is a constructor.
pub struct FunctionHead {
    /// What the definition writes before its name, with the specifiers above removed. `None` for a constructor, a
    /// destructor and an `operator` — the three shapes that write no return type.
    pub returns: Option<String>,
    /// The name as written: `f`, `~S`, `S`, `operator+`.
    pub name: String,
    /// Where that name is, for a diagnostic. The whole span for an `operator`, which is not one token.
    pub name_range: cpp_parser::SourceRange,
}

/// **The return type a function definition writes**, as [`function_head`] reads it.
///
/// Kept as a named function because it is the question three checks ask; it is one line over the head reader so that
/// the type, the name and the name's range cannot come from three readers that disagree.
pub fn return_type_written_by(function: &cpp_parser::CppSyntaxNode) -> Option<String> {
    function_head(function)?.returns
}

/// Read a function's head — see [`FunctionHead`].
pub fn function_head(function: &cpp_parser::CppSyntaxNode) -> Option<FunctionHead> {
    use cpp_parser::CppAstNode;

    // **Anchored on the parameter list**, found through the typed AST: a function's name is written immediately
    // before its `(`, in every spelling. `CppParamList::cast` rather than a kind comparison, because the node is
    // `ParameterList` — a kind this grammar does not have under that name, so a kind comparison matched nothing.
    let parameters = function_parameters(function)?;
    let open = usize::from(parameters.syntax().text_range().start());

    // **A member function template's head does not begin with its template parameters**, which are written before the return
    // type: `template<class T> void f()` returns `void`, not the template header.
    let template_head = cpp_parser::CppDeclaration::cast(function.clone())
        .and_then(|declaration| {
            declaration
                .children::<cpp_parser::CppTemplateParamList>()
                .next()
        })
        .map(|list| span_of(list.syntax()));

    // Every non-trivia token of the head, in order: everything before the `(`.
    let head: Vec<cpp_parser::CppSyntaxToken> = function
        .descendants_with_tokens()
        .filter_map(|element| element.into_token())
        .filter(|token| usize::from(token.text_range().end()) <= open)
        .filter(|token| !cpp_parser::is_trivia(cpp_parser::CppTokenKind::from(token.kind())))
        .filter(|token| {
            let range = token.text_range();
            let (start, end) = (usize::from(range.start()), usize::from(range.end()));
            !template_head
                .is_some_and(|(head_start, head_end)| head_start <= start && end <= head_end)
        })
        .collect();

    // **The name.** An `operator` is spelled `operator` plus a symbol and is not an identifier at all; a destructor
    // is `~` plus the class name; everything else ends at its last identifier.
    // **The name, and where it starts — which is also where the return type ends.**
    //
    // An `operator` is spelled `operator` plus a symbol and is not an identifier at all; a destructor is `~` plus the
    // class name; everything else ends at its last identifier. In all three the name **begins** at the token this
    // finds, and the head the return type is read from is what comes before that.
    let (name, name_range, name_starts_at) =
        match head.iter().position(|token| token.text() == "operator") {
            Some(at) => {
                let last = head.last()?;
                (
                    head[at..]
                        .iter()
                        .map(|token| token.text().to_string())
                        .collect::<String>(),
                    cpp_parser::source_range(head[at].text_range().cover(last.text_range())),
                    at,
                )
            }
            None => {
                let at = head.iter().rposition(|token| {
                    token.kind() == cpp_parser::CppTokenKind::Identifier.into()
                })?;
                // A leading `~` belongs to the name: `~S` is a destructor, and a caller comparing the name with the
                // enclosing class has to see the same spelling the reader wrote.
                let start = if at > 0 && head[at - 1].text() == "~" {
                    at - 1
                } else {
                    at
                };
                (
                    head[start..=at]
                        .iter()
                        .map(|token| token.text().to_string())
                        .collect::<String>(),
                    cpp_parser::source_range(head[start].text_range().cover(head[at].text_range())),
                    start,
                )
            }
        };
    let before_the_name = &head[..name_starts_at];

    // What is left before the name, minus the specifiers that are not a type.
    //
    // **Rebuilt from the tokens with the separation the SOURCE has, not the rendering.** The rendering collapses
    // whitespace, so its text for `int S::f() { }` is `int S::f() { }` — the type `int` and the *name's* scope `S::`
    // standing next to each other with nothing between them, which no reading of that text can tell apart. Measured,
    // every attempt to slice it gave `Some("int S::")`.
    //
    // The token stream keeps what the file wrote: `int` and `S` are two tokens with a space between them in the
    // source, and a `::` is a token of its own. Reading each token's own text and inserting the **source's** gap
    // between neighbours reconstructs the head as the reader wrote it, which is what a message has to show.
    let mut returns = String::new();
    let mut previous_end: Option<usize> = None;
    let own_text = function.text().to_string();
    let function_starts = usize::from(function.text_range().start());
    for token in before_the_name {
        let range = token.text_range();
        let (start, end) = (usize::from(range.start()), usize::from(range.end()));
        if let Some(previous_end) = previous_end {
            let gap = source_between(&own_text, function_starts, previous_end, start);
            returns.push_str(gap);
        }
        returns.push_str(token.text());
        previous_end = Some(end);
    }
    for specifier in NOT_A_TYPE {
        // Whole words only: `static_cast` is not a storage class, and neither is a type whose name contains one of
        // these spellings.
        returns = returns
            .split(' ')
            .filter(|word| word.trim() != *specifier)
            .collect::<Vec<_>>()
            .join(" ");
    }
    let returns = returns.trim().to_string();

    // **A qualified definition writes its scope, and the scope is not the type.** `int S::f()` writes `S::` in the
    // head between the return type and the name, and a reader that took "everything before the name" collected it:
    // measured, `Some("int S::")`.
    //
    // The head this reads **ends at the name**, so the scope of the declared name is simply a `::` that the head ends
    // with, and what precedes it is the type. What must not be cut is the scope *within* a type: `const std::string&
    // f()` puts `const std::string&` here, and it does not end with a `::` at all.
    //
    // This is the second judgement written for it. The first asked whether the text after the `::` started with the
    // name — which is empty here by construction, so it matched nothing and `int S::f()` kept its `S::`; the second
    // asked whether the text before it ended with the name, which compares the *scope's* name (`S`) against the
    // *function's* (`f`) and so also matched nothing. Both were answers to a question this reader had already
    // answered by cutting the name off.
    let mut returns = returns.trim().to_string();
    if returns.ends_with("::") {
        returns = strip_trailing_scopes(&returns);
    }
    // `int*` and `int *` are one type; the `*` run is kept as written, so `int *` is the spelling given back.
    let returns = returns.trim().to_string();

    // **The three shapes C++ gives no return type to.** `~S` and `operator*` are spelled that way and no scope
    // table would name them; a constructor is an *ordinary identifier* whose name is the class's, which is why it
    // is the one case this cannot decide from the name alone and asks the enclosing class instead.
    let returns = if returns.is_empty()
        || name.starts_with('~')
        || name.starts_with("operator")
        || declares_the_enclosing_class_named(function, &name)
    {
        None
    } else {
        Some(returns)
    };

    Some(FunctionHead {
        returns,
        name,
        name_range,
    })
}

/// **The gap the source has between two offsets**, or a single space when it cannot be read.
///
/// Used by [`function_head`] to put the separation back between tokens: the rendering removes whitespace, so its text
/// has `int` and `S` adjacent where the file wrote a space, and `int S::f()` is unreadable from that text alone.
/// Plain bytes rather than a comment-aware scan, because what stands between two tokens of one function's head is
/// whitespace — anything else would be a token, and a token is one of the two ends.
fn source_between(function_text: &str, function_starts: usize, from: usize, to: usize) -> &str {
    let (from, to) = (
        from.saturating_sub(function_starts),
        to.saturating_sub(function_starts),
    );
    function_text.get(from..to).unwrap_or(" ")
}

/// **Drop every scope name a head ends with** — `int a::b::` becomes `int`.
///
/// The head a definition writes ends at the name it declares, so a qualified definition leaves the scopes it reached
/// the name through: `int S::f()` reads as `int S::`, and `int a::b::c()` as `int a::b::`. Each `word::` at the end is
/// one of those scopes and none of them is a type.
///
/// A **loop** rather than one pass, because a namespace nests: measured, one pass left `int a:` from `int a::b::c()`
/// — the first scope went and the second stayed, and the answer named a type that does not exist.
fn strip_trailing_scopes(head: &str) -> String {
    let mut head = head.trim_end().to_string();
    while head.ends_with("::") {
        head.truncate(head.len() - 2);
        head = head.trim_end().to_string();
        // The scope's own name goes with it — the last identifier-shaped word, removed as a whole.
        //
        // Splitting on "not alphanumeric or `_`" is what went wrong twice here: measured, `int a::b::` left `int a:`
        // and then `int a`, because the split ran on the *colons* and on the space instead of on the word boundary.
        // The word is what has to go, so the boundary is what it is found by.
        let word_starts = head
            .rfind(|character: char| !(character.is_alphanumeric() || character == '_'))
            .map(|at| at + 1)
            .unwrap_or(0);
        head.truncate(word_starts);
        head = head.trim_end().to_string();
    }
    head
}

/// See [`missing_return::declares_the_enclosing_class`]'s rule, applied to a name that has already been read.
///
/// Here rather than in the caller because the head reader is what has the name and the node, and a second walk of
/// the ancestors from outside would be a second answer to the same question.
fn declares_the_enclosing_class_named(function: &cpp_parser::CppSyntaxNode, name: &str) -> bool {
    use cpp_parser::{CppAstNode, CppClassDef, CppCompoundStat};

    // **The nearest class-like definition, by name**, and a body stops the walk: a class declared inside a function does not
    // enclose it. The name is the definition's own (`get_name_text`), not the last identifier written before its body.
    for ancestor in function.ancestors().skip(1) {
        if CppCompoundStat::can_cast(ancestor.kind().into()) {
            return false;
        }
        if let Some(class) = CppClassDef::cast(ancestor.clone()) {
            return class
                .get_name_text()
                .is_some_and(|declared| declared == name.trim_start_matches('~'));
        }
    }
    false
}
/// **The last identifier written inside a node** — the name a call would spell, the name a declaration declares.
///
/// Shared by the two checks that pair a call with a declaration, because both need the same answer to "which name
/// is this": the *last* one written, so that a return type (`int scale(…)`), a scope (`w.scale(…)`) and a template
/// head (`vector<int>::push_back(…)`) all end at the name and not at something before it.
pub fn spelling_of(node: &cpp_parser::CppSyntaxNode) -> Option<String> {
    node.descendants_with_tokens()
        .filter_map(|element| element.into_token())
        .filter(|token| token.kind() == cpp_parser::CppTokenKind::Identifier.into())
        .last()
        .map(|token| token.text().to_string())
}

/// **The name a call is to** — `f` for `f(x)`, `push_back` for `v.push_back(x)`, `free` for `ns::free(p)`.
///
/// Asked of the callee's **expression**, not of the last identifier written inside it: `(*p)(x)` is a call through a pointer,
/// and the last identifier in it is `p` — a name the call does not name, which a token walk would look up as a function.
pub fn callee_name_of(callee: &cpp_parser::CppExpr) -> Option<String> {
    use cpp_parser::CppExpr;
    let token = match callee {
        CppExpr::NameExpr(name) => name.get_last_name_token(),
        CppExpr::IndexExpr(index) => index.get_member_name(),
        CppExpr::MemberExpr(member) => member.get_member_name(),
        // A parenthesised, dereferenced or cast callee is not a name the caller wrote.
        _ => None,
    }?;
    Some(token.get_name_text().to_string())
}

/// **The name token a declaration or definition writes** — the last non-trivia token before its parameter list.
///
/// This is the one place that answers *where the name is*, and everything that needs the name comes through it:
/// [`name_declared_by`] takes its text and a diagnostic takes its range. One question, one implementation — the
/// alternative is what this replaced, which was two readers of the same fact that disagreed.
///
/// # Why the parameter list is the anchor
///
/// Because a function's name is written immediately before its `(`, in every spelling this layer sees: `int f()`,
/// `void C::f()`, `Name::~Name()`, `operator int()`, `int (S::*p)()`. A reader that anchored on anything else had to
/// decide which of the tokens before the list is *the* name, and both earlier attempts got that wrong in a different
/// way:
///
/// ```text
///   "the last child ending before the parameter list starts"
///       `take_while` stops at the FIRST child that ends after it — and the first child of
///       `int unfinished() { }` is `DeclSpecifierSeq \"int \"`, which does not. So the head was
///       empty and name_declared_by answered None for every definition. Measured.
///   "the first identifier spelled like the name"
///       matched the return type, and produced a range from `int` to the end of the file. Measured.
/// ```
///
/// The list is found through the **typed** AST ([`CppParamList`](cpp_parser::CppParamList)) rather than by comparing
/// node kinds: the kind is `ParameterList`, a kind this grammar does not have under that name, so a kind comparison
/// silently matched nothing — which is the trap `status.md` §5 records and the reason its rule is to use `cast`.
///
/// The **token** is returned rather than its text, because the two callers want different halves of it and both are
/// cheaper from here: [`name_declared_by`] takes the spelling, and a diagnostic takes the range.
pub fn name_token_of(function: &cpp_parser::CppSyntaxNode) -> Option<cpp_parser::CppSyntaxToken> {
    use cpp_parser::CppAstNode;

    let parameters = function_parameters(function)?;
    let open = usize::from(parameters.syntax().text_range().start());

    function
        .descendants_with_tokens()
        .filter_map(|element| element.into_token())
        .filter(|token| usize::from(token.text_range().end()) <= open)
        .filter(|token| !cpp_parser::is_trivia(cpp_parser::CppTokenKind::from(token.kind())))
        .filter(|token| token.kind() == cpp_parser::CppTokenKind::Identifier.into())
        .last()
}

/// **The name a function declares** — see [`function_head`], which reads it together with the return type and
/// therefore cannot disagree with it about which name it found.
pub fn name_declared_by(function: &cpp_parser::CppSyntaxNode) -> Option<String> {
    Some(function_head(function)?.name)
}

/// **A function's parameters as the declaration spells them** — `int count`, `const Widget& w`, `...`.
///
/// Read from the **tree** and never from [`DeclFact::parameters`](crate::DeclFact::parameters), which is the
/// template parameter list: the check this one replaces read that field and reported 119 findings on 200 MSVC
/// headers, every one of them a function whose real parameters were in the tree all along.
pub fn parameter_spellings_of(function: &cpp_parser::CppSyntaxNode) -> Vec<String> {
    use cpp_parser::{CppAstNode, CppDeclaration, CppParam};
    let Some(parameters) =
        CppDeclaration::cast(function.clone()).and_then(|declaration| declaration.get_param_list())
    else {
        return Vec::new();
    };
    parameters
        .children::<CppParam>()
        .map(|parameter| parameter.get_type_text())
        .filter(|spelling| !spelling.is_empty())
        .collect()
}
/// **Can a value of this type build an object of that class?** — asked of the **index**, never of a tree.
///
/// ```text
///   Some(true)    a constructor could take it: the class has a constructor whose parameter could accept this type
///   Some(false)   nothing in the class can: it has constructors and none of them could, or it has none at all
///   None          not this layer's question: the class is not in the index, or a parameter is written in a way
///                 that decides nothing (`_Ty`, a template parameter, a type from a header nobody indexed)
/// ```
///
/// # Why the facts and not the tree
///
/// `CppMember` carries the class's own [`DeclFact`], and a function's `DeclFact::parameter_list` is **the parameter
/// list as its file spells it** — stored, in the index's own words, *"because a query holds one file and the
/// parameters are written in another… re-parsing that header per member query is the cost this field exists to
/// avoid"*. That is exactly this question: `std::string x = 123;` is asked from a `.cpp` whose `<string>` is not its
/// own text, and the answer is a fact about `<string>` that the index already holds.
///
/// A check that instead walked the **rendering** for the class would be doing the work this field exists to prevent
/// — and would find nothing at all when the class comes from a header, which is the case that matters.
///
/// # The rule, and why it is this narrow
///
/// A value whose type is arithmetic (or a literal) is compatible with a parameter that is arithmetic, `bool`,
/// `char`-like, or a **template parameter** — anything a template could instantiate to. It is **not** compatible
/// with a pointer or reference to a non-arithmetic type: `MyString(const char*)` cannot be built from `1231`, which
/// is the whole of the `std::string x = 123;` case. Everything else — a class parameter, a name this cannot classify
/// — answers `None`, because a conversion this layer cannot see is not a conversion the program does not have.
pub fn a_class_can_be_built_from(
    context: &CheckContext<'_>,
    class: &str,
    value: &crate::sema::types::Type,
) -> Option<bool> {
    // **A target that names no class is a question this cannot answer**, and asking it is not free: the name goes to
    // the index, which resolves it, finds nothing, and falls back to a definition query and a member walk. Measured on
    // EmmyLuaCodeStyle's `LuaParser/src/File/LuaSource.cpp` — a file whose assignments are all to `int`/`size_t`
    // locals — `assign-type-check` took **963 ms**, and the calls that took it there were the ones with an empty
    // class name: `assign-type-check` asks with `class_name().unwrap_or_default()`, which is `""` for a builtin.
    //
    // `None` is the honest answer: a builtin type has no constructors to ask about, and this facility is only about
    // "does this class have a constructor that could take this value".
    if class.is_empty() {
        return None;
    }

    // **A value that is itself a class is not a question this can answer.**
    //
    // The `Some(false)` at the end of this function means *"an aggregate cannot be built from one scalar value"* —
    // which is true, and is not every case that reaches it: copy-initialisation of an aggregate from an object of its
    // own type is legal C, and it is what `div_t divided = div(7, 2);` writes. Measured on a nine-file C corpus (and
    // reproduced in `tests/checks.rs` with the declaration in a header): three findings in one function, for
    // `div`/`ldiv`/`lldiv`, where the value's type *is* the target's — through two typedefs, `div_t` → `_div_t` — the
    // conversion relation answered `Implicit` for the spelling and `Unknown` for the class, and the aggregate arm then
    // called a legal copy "does not convert".
    //
    // `parameters_that_could_accept` already refuses to decide for a non-arithmetic value; this is the same refusal one
    // level up, where the constructor loop is not there to make it.
    if !value.is_arithmetic() {
        return None;
    }

    // **The class's own members, not its whole inheritance graph.** `members_of` answers the question a *reader*
    // asks — what can be written after `.` — and walks the base chain to do it: measured on `test_module`'s
    // `import std;` file, `members_of("std::vector")` is **ten bases and 583 ms of walking**, while the class's own
    // list is 16 ms and comes back empty. This check wants one thing from the class — whether one of *its own*
    // constructors could take this value, inherited ones explicitly excluded below — so that walk is work for an
    // answer it discards.
    //
    // Measured on the same file, `assign-type-check` was **1 221 ms of a 1 497 ms diagnostic pass**, two calls of
    // this function at ~600 ms each, and a diagnostic runs on every pull: that is the latency a reader feels.
    let crate::Known::Yes(members) = context.model.own_members_of(class) else {
        return None;
    };

    // **An empty member list is not "no constructors".** `own_members_of` answers from this file's scopes and the
    // index, so a class it knows of but has no members recorded for — a forward declaration, a class whose defining
    // file the index has not read, a class template whose members are filed under a scope this reading cannot see —
    // comes back **empty**, and reading that as "nothing can build it" is how this rule reported a class that has
    // exactly the constructor its value needs: measured, `Widget(int size)` in a second project file produced
    // `0 members []` and a finding.
    if members.is_empty() {
        return None;
    }

    // **The members declared in the class itself**: an inherited constructor is not this class's, which is the other
    // half of why the base walk was not needed — nothing it adds can be a constructor of this class.
    let mut constructors = 0usize;
    for (_, fact) in &members {
        let name = fact.name.as_str();
        let is_a_constructor = name == class.rsplit("::").next().unwrap_or(class);
        // **A conversion operator is a way to build the class that has no parameter list to compare against** —
        // `operator Widget()` — so its presence means this question is not decided here.
        if name.starts_with("operator") {
            return None;
        }
        if !is_a_constructor {
            continue;
        }
        let Some(parameters) = fact.parameter_list.as_deref() else {
            continue;
        };
        constructors += 1;

        match parameters_that_could_accept(parameters, value) {
            // One constructor that could take the value is enough for this rule to have nothing to say.
            Some(true) => return Some(true),
            // A parameter written in a way that decides nothing: the class may still be buildable.
            None => return None,
            Some(false) => {}
        }
    }

    // **No constructor at all is a class no value can build.** A class with no constructor is an aggregate, and an
    // aggregate cannot be initialised from a single value: `struct S { int size; }; S s = 1231;` does not compile.
    // (A braced list of matching members is a different rule and a different shape - `S s{1231}`.)
    let _ = constructors;
    Some(false)
}

/// **Whether one written parameter list holds a parameter that could accept this value** — see
/// [`a_class_can_be_built_from`] for the rule and why it is this narrow.
fn parameters_that_could_accept(written: &str, value: &crate::sema::types::Type) -> Option<bool> {
    // The value has to be something this can classify. A class-to-class conversion is a question about two
    // declarations, and this is asked with one of them in hand.
    if !value.is_arithmetic() {
        return None;
    }

    let inner = written.trim().trim_start_matches('(').trim_end_matches(')');
    let mut depth = 0i32;
    let mut parameters: Vec<String> = Vec::new();
    let mut current = String::new();
    for character in inner.chars() {
        match character {
            '<' | '(' | '[' => depth += 1,
            '>' | ')' | ']' => depth -= 1,
            // **A comma at depth zero separates parameters** — the whole reason this is counted rather than split:
            // `std::pair<int, int>` is one parameter with a comma in it.
            ',' if depth == 0 => {
                parameters.push(std::mem::take(&mut current));
                continue;
            }
            _ => {}
        }
        current.push(character);
    }
    parameters.push(current);

    // **One value fills one parameter.** A constructor written with two parameters cannot be built from one value,
    // unless one of them has a default — `basic_string(size_type _Count, _Elem _Ch)` takes two, `_Ty(int, int = 0)`
    // takes one. Without this, `struct S { S(int, int); }; S s = 123;` was read as buildable because `int` accepts an
    // `int`, which is the arity question answered by the wrong rule.
    if parameters.len() > 1 {
        return if parameters.iter().any(|parameter| parameter.contains('=')) {
            None
        } else {
            Some(false)
        };
    }

    let mut any = false;
    for parameter in parameters {
        let Some(classified) = could_take_an_arithmetic_value(&parameter) else {
            // A parameter this cannot classify decides nothing — a template parameter, an unknown name.
            return None;
        };
        any = true;
        if classified {
            return Some(true);
        }
    }
    any.then_some(false)
}

/// **Could a parameter written like this accept an arithmetic value?**
///
/// `None` for a parameter that decides nothing: a template parameter (`_Ty`, `T`, `class _Elem`), an `auto`, or a
/// name that is neither an arithmetic type nor a pointer to one.
fn could_take_an_arithmetic_value(parameter: &str) -> Option<bool> {
    let mut written = parameter.trim();

    // Drop a default argument: `int n = 0` is an `int`, and the `=` and everything after it is not the type.
    if let Some(at) = written.find('=') {
        written = written[..at].trim();
    }
    if written.is_empty() || written == "..." || written.ends_with("...") {
        // `...` takes anything, which is a parameter that could accept the value.
        return Some(written == "..." || written.ends_with("..."));
    }

    // The type is everything before the name: `const Widget& w` and `const Widget&` are the same type.
    let words: Vec<&str> = written.split_whitespace().collect();
    let (type_words, _name) = match words.as_slice() {
        [] => return None,
        [only] => (vec![*only], ""),
        [rest @ .., last] => (rest.to_vec(), *last),
    };
    let type_written = type_words.join(" ");

    let arithmetic = |word: &str| {
        let word = word.trim_start_matches("const").trim();
        matches!(
            word,
            "int"
                | "long"
                | "short"
                | "char"
                | "signed"
                | "unsigned"
                | "float"
                | "double"
                | "bool"
                | "wchar_t"
                | "char8_t"
                | "char16_t"
                | "char32_t"
                | "size_t"
                | "std::size_t"
                | "ptrdiff_t"
                | "int64_t"
                | "uint64_t"
                | "int32_t"
                | "uint32_t"
                | "std::int64_t"
                | "std::uint64_t"
        )
    };

    // A pointer or reference **to something that is not arithmetic** cannot be built from a number:
    // `MyString(const char*)` is the constructor `std::string` has and `1231` does not fit it.
    let behind_the_operator = type_written
        .split(['*', '&'])
        .next()
        .unwrap_or_default()
        .trim()
        .trim_start_matches("const")
        .trim();
    let is_a_pointer_or_reference = type_written.contains('*') || type_written.contains('&');

    if is_a_pointer_or_reference {
        // **A pointer is not an arithmetic value; a reference to one is.** `const int&` binds an `int`, so the reference case
        // asks about the type behind it — but `const char*` is a pointer, and an `int` does not convert to it. The first
        // version asked the same question for both, which is how `std::string(const char*)` came back "this constructor can
        // take `123131`" and the whole class case answered `Some(true)`.
        if type_written.contains('*') {
            return Some(false);
        }
        return Some(arithmetic(behind_the_operator));
    }

    let bare = type_written.trim_start_matches("const").trim();
    if arithmetic(bare) {
        return Some(true);
    }

    // **A template parameter takes whatever it is instantiated with** — `_Ty`, `_Elem`, `class _Ty`, `typename T`.
    let looks_like_a_template_parameter = bare.starts_with('_')
        || bare == "T"
        || bare.len() == 1
        || bare.starts_with("class ")
        || bare.starts_with("typename ");
    if looks_like_a_template_parameter {
        return None;
    }

    // **A name with no `*` or `&` and no `(` is a class by value** — `MyString(Widget)` cannot take a number.
    Some(false)
}

/// **Run every check, in the order a consumer should show them**, and answer what they found.
///
/// The list is the registry: a check that is not here does not run. See the module documentation for why these are
/// typed calls rather than closures with an index.
pub fn run(context: CheckContext<'_>) -> Vec<Finding> {
    let mut context = context;

    // **A reading the parser could not finish gets no semantic findings.**
    //
    // Every rule below asks the tree and the index about a *program*, and a tree with a syntax error is not the
    // program: the parse recovered somewhere, and what it recovered into is a guess. Measured on a nine-file C corpus:
    // a single unread construct (`__typeof__(struct point) origin = {1, 2};`) left one file's summary unusable and
    // produced **20 findings** — every call and every member in it "not declared", not one of them about the reader's
    // code. Nothing is hidden by this: the parse errors are published by the channel built for them
    // (`FileDiagnostics::errors`, which `diagnose_file` sends first), and the text-level rules below still run — an
    // include that is not on the search path and a macro redefined are facts about the file whoever could parse it.
    run_check::<include_not_found::IncludeNotFound>(&mut context);
    // **A type used but not included** — see the module. It runs first because the fix it exists for is a fix, and the
    // finding is only worth the noise if it can name where the type comes from.
    run_check::<missing_include::MissingInclude>(&mut context);
    run_check::<macro_redefined::MacroRedefined>(&mut context);
    run_check::<macro_parentheses::MacroParentheses>(&mut context);
    if !context.errors.is_empty() {
        return std::mem::take(&mut context.findings);
    }

    // **`syntax_error` is NOT run, and this is where the duplicate was.**
    //
    // It is the one check that does not reason about the program — it republishes what the parser already answered —
    // and those answers are **already a channel of their own**: `FileDiagnostics::errors` carries
    // `cooked.diagnostics`, which `handlers::diagnostic::diagnose_file` publishes first. Running the check as well
    // put every parse error on the wire **twice**, which is what was reported and what
    // `handshake.rs`'s `a_pulling_client_gets_a_report_and_not_null` asserts against:
    //
    // ```text
    // PROBE channels: errors=1 checks=1 notes=0   →   final: 2 items, both `expected \`;\``
    // ```
    //
    // One error from the channel built for it, one from the check that copies it. The fix is not to stop publishing
    // either one — it is to stop having two. `errors` is the one kept, because it is the channel that carries the
    // parser's own diagnostics and the `unplaced` count with them; the check is left in the tree, compiled and
    // documented, for the reader who wants to know how the two ever came apart. `DiagnosticCode::SyntaxError` is
    // still the code every parse error is published under, and `syntax_error_is_reported` still passes, because it
    // collects `errors` as well as `checks`.
    //
    // The **order** that check's own note argues for is kept by construction: `diagnose_file` chains `found.errors`
    // before `check_findings`, so a reader is still told what to fix before what the fixed text will still be wrong
    // about.
    //
    // `include_not_found`, `macro_redefined` and `macro_parentheses` are **not** here: they read the file's text rather
    // than the tree, so they run at the top of this function, where a file that did not parse still gets them.
    run_check::<unused::Unused>(&mut context);
    // **The style rules**, named after clang-tidy's own — see each module for what it will say and why it is worth saying.
    // They are registered and do nothing yet: a rule with a name, a code and a test is what the next pass fills in.
    run_check::<braces_around_statements::BracesAroundStatements>(&mut context);
    run_check::<use_nullptr::UseNullptr>(&mut context);
    run_check::<concept_not_satisfied::ConceptNotSatisfied>(&mut context);
    run_check::<use_override::UseOverride>(&mut context);
    run_check::<simplify_boolean_expr::SimplifyBooleanExpr>(&mut context);
    run_check::<else_after_return::ElseAfterReturn>(&mut context);
    run_check::<cstyle_cast::CStyleCast>(&mut context);
    run_check::<use_auto::UseAuto>(&mut context);
    // `macro_parentheses` is **not** here: it reads macro facts rather than the tree, so it runs with the other
    // text-level rules at the top of this function — where a file that did not parse still gets it.
    // **The first rule that cannot be written from the text**: whether `if (x)` is a conversion depends on `x`'s **type**,
    // which is the scope tree and the index, not the spelling.
    run_check::<implicit_bool_conversion::ImplicitBoolConversion>(&mut context);
    run_check::<access_invisible::AccessInvisible>(&mut context);
    run_check::<missing_return::MissingReturn>(&mut context);
    run_check::<assignment_in_condition::AssignmentInCondition>(&mut context);
    run_check::<unnecessary_branch::UnnecessaryBranch>(&mut context);
    run_check::<undefined_field::UndefinedField>(&mut context);
    run_check::<undefined_name::UndefinedName>(&mut context);
    run_check::<redefinition::Redefinition>(&mut context);
    run_check::<argument_count::ArgumentCount>(&mut context);
    run_check::<param_type_check::ParamTypeCheck>(&mut context);
    run_check::<assign_type_check::AssignTypeCheck>(&mut context);
    run_check::<return_type_mismatch::ReturnTypeMismatch>(&mut context);
    // The rule that needs an expression origin: `return s;` is a defect or not depending on whether `s` is a local, a
    // parameter or a static - a question about the scope tree rather than about the spelling.
    run_check::<dangling_return::DanglingReturn>(&mut context);
    // The same origin analysis, asked about a member instead of a `return`: a view of a by-value parameter, or of a
    // temporary, outlives what it refers to.
    run_check::<dangling_field::DanglingField>(&mut context);
    // The third rule of the lifetime family: a pointer read after its memory was freed, including a free written in
    // another function and recorded on that function fact.
    run_check::<use_after_free::UseAfterFree>(&mut context);
    // **The Unreal Engine conventions**, which only a project that says it is engine code runs — see `[unreal]`.
    run_check::<ue_naming::UeNaming>(&mut context);
    run_check::<ue_generate_body::UeGenerateBody>(&mut context);
    run_check::<ue_generated_header::UeGeneratedHeader>(&mut context);
    run_check::<ue_macro_scope::UeMacroScope>(&mut context);
    run_check::<ue_specifier::UeSpecifier>(&mut context);

    context.into_findings()
}

/// **The member access a callee is the name of** — `push_back` in `v.push_back(…)`.
///
/// `member_access_of` answers for the **node that holds the operator**, and a call's callee is the identifier to its
/// right: the access is the parent. Walking up a couple of levels rather than asserting the shape keeps this honest for
/// the grammar's other spellings (`(*p).f`, `a.b.f`), where the callee's parent is not always the outermost access.
pub fn member_access_above(
    node: &cpp_parser::CppSyntaxNode,
) -> Option<crate::sema::resolve::MemberAccess> {
    let mut current = Some(node.clone());
    for _ in 0..3 {
        let node = current?;
        if let Some(access) = crate::sema::resolve::member_access_of(&node) {
            return Some(access);
        }
        current = node.parent();
    }
    None
}