cpp_code_analysis 0.4.0

The analysis layer of cpp_ls: the preprocessor, symbol scopes, type inference and the semantic checks.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
//! Call signatures: which function is being called, and which parameter the cursor is in.
//!
//! The interesting half is the *active parameter*: the cursor is not on a parameter, it is between two of them, and
//! the states a half-typed call goes through are all different — nothing written, one argument written, a comma
//! just typed. Each is pinned here, and so is the refusal: a cursor on the callee is not a call being typed.

use cpp_code_analysis::signature::CallSignature;
use cpp_code_analysis::{
    CompilerConfig, MemoryFiles, OpenDocuments, Session, SessionFiles, WatchFilter,
};

fn session_with(files: &[(&str, &str)]) -> Session<MemoryFiles> {
    let mut memory = MemoryFiles::new();
    for (path, source) in files {
        memory = memory.with_file(*path, *source);
    }

    let providers = SessionFiles::new(OpenDocuments::new(), memory);
    let mut session = Session::with_config(
        "/p",
        providers,
        WatchFilter::new("/p"),
        CompilerConfig::default(),
    );
    session.add_project_files(
        files
            .iter()
            .map(|(path, _)| std::path::PathBuf::from(*path)),
    );

    // **The ask, and then the pump** - see `tests/completion.rs`'s `cooked_view`. A view is of the file's *cooked
    // reading*, and a rendering is built because something asked for it.
    for (path, _) in files {
        session.want_cooked_reading(std::path::Path::new(path));
    }
    session.index_everything();

    session
}

/// The signature at a cursor written in the fixture as `|`.
///
/// The marker is the whole point of the fixture: the states under test differ by *where* the cursor is, so a test
/// that passed an offset by hand would be a test of the arithmetic rather than of the analysis.
///
/// **One** signature, because that is what all but one of these fixtures declare — the overload case is its own test
/// below, and it is the plural that is the API: a name with four declarations has four signatures, and a test helper
/// that took the first would hide exactly the thing worth pinning.
fn signature_where_marked(source: &str) -> (String, Option<CallSignature>) {
    let offset = source.find('|').expect("the fixture marks the cursor");
    let without_marker = source.replace('|', "");

    let session = session_with(&[("/p/a.cpp", &without_marker)]);
    let view = session.view("/p/a.cpp").expect("the file is held");

    let signature = {
        // **The cursor the fixture marks is the file's; `signatures_at` reads the rendering.** A comment is removed
        // before the parse, so the two offsets differ by everything the cook deleted — 46 bytes on the fixture below,
        // which put the cursor in the middle of the *declaration* and made every signature answer `None`. Measured:
        // this one helper is the reason all five of this suite's failures were about a call that resolves.
        let in_the_reading = view
            .reading_offset_of(cpp_code_analysis::file::coordinates::FileOffset::new(
                offset,
            ))
            .expect("the cursor is in the rendering");
        session
            .signatures_at(&view, in_the_reading)
            .into_iter()
            .next()
    };

    (without_marker, signature)
}

/// **A constructor call is a call** — `Widget(|)` should offer `Widget(int size, int extra)`, and today offers
/// nothing.
///
/// **The cause is in the grammar, not here**, and finding that took two rounds of measurement:
///
/// ```text
///   SIGNATURES call "Widget()" callee "Widget" -> 1 candidate(s)   the call and the class are both found
///   CONSTRUCTORS `Widget` at 6: [23]                               and a member named `Widget` is found in it
///   SOURCE at 23: list None                                        but its parameter list cannot be read
/// ```
///
/// `cpp_dump` says why — a constructor declaration inside a class body is parsed as a **variable**:
///
/// ```text
///   Declaration@27..56
///     DeclSpecifierSeq@27..33 > NamedType > NameExpr "Widget"   <- the class name became the TYPE
///     InitDeclarator@33..54 > Declarator@33..54
///       ParameterList@33..54                                    <- the list hangs off a nameless declarator
/// ```
///
/// So there is no constructor *declaration* in the tree for a signature to be rendered from. The same gap is what
/// makes MSVC's `sprintf_s` arrive in the index as a `Variable` with `type=Some("_CSTD")` — measured while chasing
/// a false positive in `unused` — so it is one grammar defect with several symptoms, and it is why this test is
/// ignored rather than fixed here.
///
/// The fixture writes `Widget w = Widget(|);` rather than `Widget w(|);` on purpose: the second is the most
/// vexing parse, a **declaration** of a function `w` returning `Widget`, so there is no call at all. (The first
/// version of this test used it and measured nothing.)
#[test]
fn a_constructor_call_offers_its_parameters() {
    let source = "\
class Widget {
public:
    Widget(int size, int extra);
};

int main() {
    Widget w = Widget(|);
    return 0;
}
";
    let (_, signature) = signature_where_marked(source);
    let label = signature
        .map(|signature| signature.label)
        .unwrap_or_default();
    assert!(
        label.contains("size"),
        "the constructor's own parameters, or nothing: {label:?}"
    );
}
/// **Direct initialization is a call the grammar does not spell as one.**
///
/// `LuaParser p(file, std::move(tokens));` parses as a *declaration* whose declarator holds a parameter list, so the
/// query that looks for a call found none and the popup was empty — measured on a real project
/// (`CodeFormat.cpp:72` answered nothing while `LuaParser`'s constructors were facts in the index).
///
/// The answer is the class's constructors, and the class is the last name the declaration's specifiers write. A
/// function *definition* is the same declaration + declarator + list, and the body is what tells them apart.
#[test]
fn a_direct_initialization_offers_the_constructors() {
    let source = "\
class Widget {
public:
    Widget(int size, int extra);
};
void f() {
    Widget w(|);
}
";
    let (_, signature) = signature_where_marked(source);
    let label = signature
        .map(|signature| signature.label)
        .unwrap_or_default();
    println!("direct initialization: {label:?}");
    assert!(
        label.contains("size") && label.contains("extra"),
        "the constructor's own parameters: {label:?}"
    );
}

/// **The overload the call's arguments select comes first.**
///
/// A client whose `activeSignature` defaults to the first entry shows the language's answer; before the resolver was
/// used here it showed whichever overload the index happened to hold first — a popup that is *right* about the set and
/// wrong about the call. The list is still sent whole, so a reader can still cycle to the others.
#[test]
fn the_overload_the_arguments_select_is_the_first_signature() {
    let integer = "\
void print(int value);
void print(const char* text);
void g() {
    print(|1);
}
";
    let (_, signature) = signature_where_marked(integer);
    let label = signature
        .map(|signature| signature.label)
        .unwrap_or_default();
    assert!(
        label.starts_with("print(int"),
        "an `int` argument selects the `int` overload: {label:?}"
    );

    let text = "\
void print(int value);
void print(const char* text);
void g() {
    print(|\"x\");
}
";
    let (_, signature) = signature_where_marked(text);
    let label = signature
        .map(|signature| signature.label)
        .unwrap_or_default();
    assert!(
        label.starts_with("print(const char*"),
        "a string literal selects the `const char*` overload: {label:?}"
    );
}
/// **A template candidate is ranked as the function the call instantiates.**
///
/// The distinguishing fixture: two templates whose declared spellings (`T*` and `T`) say nothing
/// about an `int*` argument — without deduction both are `Match::Unranked` and the call is
/// ambiguous, so nothing is chosen. With it, the first is `int*` (exact) and the second is `int`
/// against an `int*` (not viable), so the `T*` one is chosen and comes first. If deduction silently
/// stopped working, this test would still pass its first half and the signature would be the `T`
/// one — so the assertion is on **which** of the two. With `int* p = &n; take(p);` the callees are
/// found (two candidates, both with their parameter lists) and the deduction is what decides
/// between them.
#[test]
fn a_template_candidate_is_ranked_as_the_function_the_call_instantiates() {
    let source = "\
template <typename T> void take(T* value);
template <typename T> void take(T value);
int g() { int n = 0; int* p = &n; take(|p); return 0; }
";
    let (_, signature) = signature_where_marked(source);
    let label = signature
        .map(|signature| signature.label)
        .unwrap_or_default();
    assert!(
        label.contains("T*"),
        "an `int*` argument selects the `T*` overload: {label:?}"
    );
}
/// **An ordinary function is what a tie means.**
///
/// The template is written **first**, so a resolution without the rule would keep the declaration order and show
/// `pick(T value)` — which is a list that is right about the set and wrong about the call. With it, `f(int)` is chosen
/// for `f(5)` even though the template deduces to exactly the same type.
#[test]
fn an_ordinary_function_beats_a_template_that_is_equally_good() {
    let source = "\
template <typename T> void pick(T value);
void pick(int value);
int g() { pick(|5); return 0; }
";
    let (_, signature) = signature_where_marked(source);
    let label = signature
        .map(|signature| signature.label)
        .unwrap_or_default();
    assert!(
        label.starts_with("pick(int"),
        "the ordinary function comes first, not the template: {label:?}"
    );
}
/// The label at the cursor, and the text each declared span points at.
fn label_where_marked(source: &str) -> (String, Vec<String>, Option<usize>) {
    let (_, signature) = signature_where_marked(source);
    let signature = signature.unwrap_or_else(|| panic!("no signature at the cursor in {source:?}"));

    let spans: Vec<String> = signature
        .parameters
        .iter()
        .map(|(range, _)| signature.label[range.clone()].to_string())
        .collect();

    (signature.label, spans, signature.active_parameter)
}

const SCALE: &str = "double scale(int count, double factor);\ndouble f() { return scale(|); }\n";

/// **A member call's second argument is its second parameter** — reported from an editor as a screenshot.
///
/// The popup for `_server->SendRequest("…", nullptr)` bolded the **first** parameter while the reader's cursor stood
/// in the second. It is the shape every real call has — a member call through a pointer, a string literal as the
/// first argument, a keyword as the second — and none of it is in the fixture the mechanism was written against.
///
/// **And the callee is in a header**, which is what makes the cursor's file offset and its *reading* offset two
/// different numbers: the rendering has the header spliced in above the call, so a signature answered at the file's
/// offset counts the commas of the wrong region. That is the half this test would have caught and the single-file
/// fixture above cannot.
#[test]
fn a_member_call_s_second_argument_is_its_second_parameter() {
    let source = "\
struct Server {
    void SendRequest(const char* method, void* params);
};
struct Client {
    void refresh() {
        _server->SendRequest(\"textDocument/diagnostic/refresh\", |nullptr);
    }
    Server* _server;
};
";
    let (label, spans, active) = label_where_marked(source);
    assert_eq!(
        spans,
        vec!["const char* method".to_string(), "void* params".to_string()],
        "the declaration's own parameters: {label:?}"
    );
    assert_eq!(
        active,
        Some(1),
        "the cursor is past the comma, which is the second parameter: {label:?}"
    );

    // **The same call, with the callee in a header the file includes.** The rendering is longer than the file by
    // everything the header contributes, so the offset the answer is computed at has to be the *reading's*.
    let header = "\
struct Server {
    void SendRequest(const char* method, void* params);
};
";
    let caller = "\
#include \"server.h\"
struct Client {
    void refresh() {
        _server->SendRequest(\"textDocument/diagnostic/refresh\", |nullptr);
    }
    Server* _server;
};
";
    let offset = caller.find('|').expect("the fixture marks the cursor");
    let without_marker = caller.replace('|', "");
    let session = session_with(&[("/p/server.h", header), ("/p/a.cpp", &without_marker)]);
    let view = session.view("/p/a.cpp").expect("the file is held");
    let in_the_reading = view
        .reading_offset_of(cpp_code_analysis::file::coordinates::FileOffset::new(
            offset,
        ))
        .expect("the cursor is in the rendering");
    let signature = session
        .signatures_at(&view, in_the_reading)
        .into_iter()
        .next()
        .unwrap_or_else(|| panic!("no signature at the cursor in {caller:?}"));
    assert_eq!(
        signature.active_parameter,
        Some(1),
        "with the header spliced in, the cursor is still in the second argument: {:?}",
        signature.label
    );
}

/// The signature is the declaration's own text, and the spans point at the parameters inside it.
#[test]
fn a_call_reports_the_declarations_own_signature() {
    let (label, spans, active) = label_where_marked(SCALE);

    assert_eq!(label, "scale(int count, double factor)");
    assert_eq!(
        spans,
        vec!["int count".to_string(), "double factor".to_string()]
    );
    assert_eq!(active, Some(0), "the cursor is in the first parameter");
}

/// **Every state a half-typed argument list goes through**, with the parameter each one is asking about.
#[test]
fn the_active_parameter_follows_the_arguments() {
    let cases = [
        ("scale(|)", 0),
        ("scale(1|)", 0),
        ("scale(1,|)", 1),
        ("scale(1, |)", 1),
        ("scale(1, 2|)", 1),
        // Past the declared parameters: the index is left as it is rather than clamped, because a variadic call
        // really is past the list.
        ("scale(1, 2, |)", 2),
    ];

    for (call, expected) in cases {
        let source =
            format!("double scale(int count, double factor);\ndouble f() {{ return {call}; }}\n");
        let (_, _, active) = label_where_marked(&source);
        assert_eq!(active, Some(expected), "in `{call}`");
    }
}

/// **A declaration in a file whose rendering nobody has built still gets a popup.**
///
/// The popup used to be answered *only* from the declaring file's tree, and that tree is a **rendering** — which a
/// query does not build (65–190 ms for a header), so `Session::view` queues one and answers `None` and the candidate
/// was skipped. A client asks once per `(`, so "the next request will have it" never happens: measured on a real
/// C++23 module project, `math::add(` answered **nothing** on its first `(` and one signature on the second, which
/// from the outside is "the signature popup almost never appears".
///
/// The fallback is the declaration's own **fact**, which every summary already carries a parameter list in. What it
/// gives up is the parameter spans; what it keeps is the label, the count and the active parameter.
#[test]
fn a_declaration_in_an_uncooked_file_still_answers() {
    // **Only the caller is cooked.** `session_with` asks for every file's rendering, which would answer this test
    // through the tree path and prove nothing; the state a fresh `(` arrives in is one where the *declaring* file
    // has no rendering yet.
    let files = [
        (
            "/p/math.cppm",
            "export module math;\nexport namespace math {\nint add(int lhs, int rhs);\n}\n",
        ),
        (
            "/p/a.cpp",
            "import math;\nint f() { return math::add(|1, 2); }\n",
        ),
    ];
    let mut memory = MemoryFiles::new();
    for (path, source) in files {
        memory = memory.with_file(path, source);
    }
    let providers = SessionFiles::new(OpenDocuments::new(), memory);
    let mut session = Session::with_config(
        "/p",
        providers,
        WatchFilter::new("/p"),
        CompilerConfig::default(),
    );
    session.add_project_files([
        std::path::PathBuf::from("/p/math.cppm"),
        std::path::PathBuf::from("/p/a.cpp"),
    ]);
    session.want_cooked_reading(std::path::Path::new("/p/a.cpp"));
    session.index_everything();

    let view = session.view("/p/a.cpp").expect("the caller is held");
    assert!(
        session.view("/p/math.cppm").is_none(),
        "the fixture is only meaningful while the declaration's file has no rendering"
    );
    let cursor = view
        .source
        .find("math::add(")
        .expect("the fixture writes the call")
        + "math::add(".len();

    let signatures = session.signatures_at(
        &view,
        cpp_code_analysis::file::coordinates::ReadingOffset::new(cursor),
    );
    assert_eq!(
        signatures.len(),
        1,
        "the fact is enough to write the label: {signatures:?}"
    );
    assert_eq!(signatures[0].label, "math::add(int lhs, int rhs)");
    assert_eq!(
        signatures[0].active_parameter,
        Some(0),
        "the count and the active parameter do not need a tree"
    );
    assert!(
        signatures[0].parameters.is_empty(),
        "the spans do need one, and are honestly absent rather than wrong"
    );
}

/// **A cursor on the callee is not a call being typed.** It is a question about the name — which is hover's and
/// definition's business — and a signature popup there would appear while the reader is still choosing the
/// function.
#[test]
fn a_cursor_on_the_callee_has_no_signature() {
    let (_, signature) =
        signature_where_marked("double scale(int count);\ndouble f() { return sca|le(1); }\n");

    assert!(signature.is_none());
}

/// A nested call answers about the **innermost** one: `outer(inner(|))` is a question about `inner`.
#[test]
fn a_nested_call_reports_the_innermost_signature() {
    let (label, _, _) = label_where_marked(
        "int inner(int depth);\nint outer(int width);\nint f() { return outer(inner(|)); }\n",
    );

    assert_eq!(label, "inner(int depth)");
}

/// A member call is the same question about the member's declaration, and the label is the *member's* spelling.
#[test]
fn a_member_call_reports_the_members_signature() {
    let (label, spans, _) = label_where_marked(
        "struct Widget { int scaled(int factor) const; };\nint f(Widget& w) { return w.scaled(|); }\n",
    );

    assert_eq!(label, "scaled(int factor)");
    assert_eq!(spans, vec!["int factor".to_string()]);
}

/// A callee in another file: the parameters are read from the header's own declaration, and the label says what
/// that declaration wrote.
#[test]
fn a_callee_in_another_file_reports_its_signature() {
    let header = "double scale(int count, double factor);\n";
    let source = "#include \"b.h\"\ndouble f() { return scale(|); }\n";
    let offset = source.find('|').expect("the fixture marks the cursor");
    let without_marker = source.replace('|', "");

    let session = session_with(&[("/p/a.cpp", &without_marker), ("/p/b.h", header)]);
    let view = session.view("/p/a.cpp").expect("the file is held");
    let in_the_reading = view
        .reading_offset_of(cpp_code_analysis::file::coordinates::FileOffset::new(
            offset,
        ))
        .expect("the cursor is in the rendering");
    let signature = session
        .signatures_at(&view, in_the_reading)
        .into_iter()
        .next()
        .expect("the header declares the callee");

    assert_eq!(signature.label, "scale(int count, double factor)");
    assert_eq!(signature.declared_in, std::path::Path::new("/p/b.h"));
}

/// **A call to an overloaded function answers every overload**, and that is the answer to "which one is this":
/// the reader picks, and the client cycles. The alternative this replaced was an empty popup — `std::format` is
/// four declarations, the name answered `Ambiguous`, and the signature was refused.
///
/// The order is the declarations' own, and each signature carries its **own** active parameter: the overloads of a
/// real function do not take the same number of parameters, so one count for the whole popup would highlight the
/// wrong one as soon as the reader switched.
#[test]
fn a_call_to_an_overloaded_function_answers_every_overload() {
    let source = "\
int scale(int count);
double scale(double factor, int places);
int f() { return scale(1, |); }
";
    let offset = source.find('|').expect("the fixture marks the cursor");
    let without_marker = source.replace('|', "");

    let session = session_with(&[("/p/a.cpp", &without_marker)]);
    let view = session.view("/p/a.cpp").expect("the file is held");
    // **The fixture's cursor is the file's; `signatures_at` reads the rendering** — see `signature_where_marked`:
    // a comment is removed before the parse, so the two offsets differ by everything the cook deleted.
    let in_the_reading = view
        .reading_offset_of(cpp_code_analysis::file::coordinates::FileOffset::new(
            offset,
        ))
        .expect("the cursor is in the rendering");
    let signatures = session.signatures_at(&view, in_the_reading);

    let labels: Vec<&str> = signatures
        .iter()
        .map(|found| found.label.as_str())
        .collect();
    assert_eq!(
        labels,
        ["scale(int count)", "scale(double factor, int places)"],
        "both declarations, in the order they are written"
    );
    assert_eq!(
        signatures[0].active_parameter,
        Some(1),
        "the cursor is past one comma, which is the *second* parameter — and the first overload has no second one"
    );
    assert_eq!(
        signatures[1].active_parameter,
        Some(1),
        "the count is the call's, and each signature reports it against its own list"
    );
}

/// **A member call to an overloaded member answers every overload too** — `s.push_back(` is two declarations in
/// `basic_string`, and the member path had been left singular while the name path became plural.
///
/// The base's overloads count as well, which is why this goes through the member *list* rather than through the
/// one member a direct lookup picks: what a reader can call on a derived object includes what its bases declare.
#[test]
fn a_member_call_answers_every_overload_of_the_member() {
    let source = "\
struct Widget {
    void scaled(int factor);
    void scaled(double factor, int places);
    void grow();
};
int f(Widget& w) { return w.scaled(|); }
";
    let offset = source.find('|').expect("the fixture marks the cursor");
    let without_marker = source.replace('|', "");

    let session = session_with(&[("/p/a.cpp", &without_marker)]);
    let view = session.view("/p/a.cpp").expect("the file is held");
    // **The fixture's cursor is the file's; `signatures_at` reads the rendering** — see `signature_where_marked`:
    // a comment is removed before the parse, so the two offsets differ by everything the cook deleted.
    let in_the_reading = view
        .reading_offset_of(cpp_code_analysis::file::coordinates::FileOffset::new(
            offset,
        ))
        .expect("the cursor is in the rendering");
    let signatures = session.signatures_at(&view, in_the_reading);

    let labels: Vec<&str> = signatures
        .iter()
        .map(|found| found.label.as_str())
        .collect();
    assert_eq!(
        labels,
        ["scaled(int factor)", "scaled(double factor, int places)"],
        "both member overloads, and not the one that is not called"
    );
}

/// **A member inherited from a base is a candidate too**, and its parameters come from the base's declaration.
#[test]
fn a_member_call_answers_an_inherited_overload() {
    let source = "\
struct Base { void scaled(int factor); };
struct Widget : Base { };
int f(Widget& w) { return w.scaled(|); }
";
    let offset = source.find('|').expect("the fixture marks the cursor");
    let without_marker = source.replace('|', "");

    let session = session_with(&[("/p/a.cpp", &without_marker)]);
    let view = session.view("/p/a.cpp").expect("the file is held");
    // **The fixture's cursor is the file's; `signatures_at` reads the rendering** — see `signature_where_marked`:
    // a comment is removed before the parse, so the two offsets differ by everything the cook deleted.
    let in_the_reading = view
        .reading_offset_of(cpp_code_analysis::file::coordinates::FileOffset::new(
            offset,
        ))
        .expect("the cursor is in the rendering");
    let signatures = session.signatures_at(&view, in_the_reading);

    assert_eq!(
        signatures
            .iter()
            .map(|found| found.label.as_str())
            .collect::<Vec<_>>(),
        ["scaled(int factor)"],
        "the base declares it, and the derived class inherits it"
    );
}

/// **A declaration laid out over several lines is one line in the popup**, and the spans still point at the
/// parameters. Measured on MSVC's `<xstring>`: three of `basic_string::append`'s nine overloads are wrapped, so this
/// is the ordinary shape in the headers this analysis reads, not a corner. The tidying is the same rule the fact's
/// own `parameter_list` gets — one implementation — and the byte map is why it can be applied to a label at all.
#[test]
fn a_wrapped_parameter_list_is_one_line_and_the_spans_follow_it() {
    let (label, spans, active) = label_where_marked(
        "int scale(int count,\n          double factor);\nint f() { return scale(|); }\n",
    );

    assert_eq!(
        label, "scale(int count, double factor)",
        "the declaration's newline and indentation are the file's layout, not the signature"
    );
    assert_eq!(
        spans,
        vec!["int count".to_string(), "double factor".to_string()]
    );
    assert_eq!(active, Some(0));
}

/// A callee in another file with several overloads: each is read from the same header, and the header is parsed
/// once for the answer rather than once per overload.
#[test]
fn overloads_in_one_header_are_read_from_it_once() {
    let header = "int scale(int count);\ndouble scale(double factor, int places);\n";
    let source = "#include \"b.h\"\nint f() { return scale(|); }\n";
    let offset = source.find('|').expect("the fixture marks the cursor");
    let without_marker = source.replace('|', "");

    let session = session_with(&[("/p/a.cpp", &without_marker), ("/p/b.h", header)]);
    let view = session.view("/p/a.cpp").expect("the file is held");
    // **The fixture's cursor is the file's; `signatures_at` reads the rendering** — see `signature_where_marked`:
    // a comment is removed before the parse, so the two offsets differ by everything the cook deleted.
    let in_the_reading = view
        .reading_offset_of(cpp_code_analysis::file::coordinates::FileOffset::new(
            offset,
        ))
        .expect("the cursor is in the rendering");
    let signatures = session.signatures_at(&view, in_the_reading);

    assert_eq!(signatures.len(), 2);
    assert!(
        signatures
            .iter()
            .all(|found| found.declared_in == std::path::Path::new("/p/b.h")),
        "both are the header's declarations"
    );
}

/// A callee nothing declares has no signature — the same refusal the parameter hints make, for the same reason.
#[test]
fn an_unresolvable_callee_has_no_signature() {
    let (_, signature) = signature_where_marked("int f() { return mystery(|); }\n");
    assert!(signature.is_none());
}

/// **A call of a class offers its constructors** — `Widget(|)` is a constructor call, and *which* overload it means
/// is overload resolution, which signature help does not do and must not pretend to do. It answers the way it answers
/// a name with several declarations: **every** constructor, in the order they are written, and the reader picks.
///
/// This test used to assert the opposite — `a_call_of_a_class_has_no_signature` — and the reasoning it recorded was
/// sound as far as it went: a class has no parameter list of its own, so there was nothing to show, and picking one
/// constructor by position would be inventing an answer. What it could not know was *why* there was nothing to show.
/// A constructor declaration inside a class body was parsed as a **variable** — measured, `Widget(int size);` came
/// out as `DeclSpecifierSeq > NamedType "Widget"` beside a nameless `Declarator` — so no constructor existed in the
/// tree at all, for this or for anything else. That is fixed in the parser (`parse_constructor_declaration`), and the
/// honest answer is now the one this test pins.
#[test]
fn a_call_of_a_class_offers_its_constructors() {
    let source = "\
struct Widget {
  Widget();
  Widget(int width, int height);
};
Widget f() { return Widget(|); }
";
    let offset = source.find('|').expect("the fixture marks the cursor");
    let without_marker = source.replace('|', "");

    let session = session_with(&[("/p/a.cpp", &without_marker)]);
    let view = session.view("/p/a.cpp").expect("the file is held");
    let in_the_reading = view
        .reading_offset_of(cpp_code_analysis::file::coordinates::FileOffset::new(
            offset,
        ))
        .expect("the cursor is in the rendering");
    let signatures = session.signatures_at(&view, in_the_reading);

    let labels: Vec<&str> = signatures
        .iter()
        .map(|found| found.label.as_str())
        .collect();
    assert_eq!(
        labels,
        ["Widget()", "Widget(int width, int height)"],
        "every constructor the class declares, in the order they are written"
    );
}

/// The documentation above the declaration comes with the signature — the place the reader needs it, because the
/// parameter they are typing is the one the comment describes.
#[test]
fn the_declarations_documentation_travels_with_the_signature() {
    let (_, signature) = signature_where_marked(
        "/// Scales a count.\n/// @param count the count\nint scale(int count);\nint f() { return scale(|); }\n",
    );
    let signature = signature.expect("the callee resolves");
    let documentation = signature.documentation.expect("the file documents it");

    assert!(documentation.get_comment_text().contains("Scales a count."));
    assert!(documentation.get_comment_text().contains("@param count"));
}

/// A call with no arguments at all, and no position inside it, is answered rather than refused: `make()` with the
/// cursor between the parentheses is the first parameter.
#[test]
fn an_empty_argument_list_is_answered() {
    let (label, _, active) =
        label_where_marked("int make(int count);\nint f() { return make(|); }\n");

    assert_eq!(label, "make(int count)");
    assert_eq!(active, Some(0));
}
/// **A call written inside a macro's argument is still that call.**
///
/// `scale(2, |)` is an argument of `PICK(...)`, so the rendering the analysis parses is not the text the file writes:
/// the macro is expanded, and the call appears inside `pick_impl((1), (scale(2, )))` — present, but under a different
/// parent and at a different offset. The cursor has to cross that seam, and the question this holds is *which token
/// the file wrote at that position*: the mapping from a file offset into the rendering asked each span where it
/// **reports** (which for anything an expansion touches is the outermost call site) instead of where it was
/// **written**, so the cursor landed before `scale` rather than inside it, the call found was the enclosing
/// `pick_impl`, and the answer was no signature at all.
#[test]
fn a_call_inside_a_macros_argument_answers_its_own_signature() {
    let source = "\
#define PICK(first, second) pick_impl((first), (second))

/// Scales a count.
int scale(int count, double factor);
int pick_impl(int first, int second);

int f() {
    return PICK(1, scale(2, |));
}
";
    let (label, spans, active) = label_where_marked(source);

    assert!(
        label.contains("scale") && label.contains("double factor"),
        "the call inside the macro argument is the one asked about: {label:?}"
    );
    assert_eq!(spans.len(), 2, "two parameters: {spans:?}");
    assert_eq!(active, Some(1), "and the cursor is on the second");
}

/// **The signature of a function-like macro call at the cursor**, through the file's own text.
///
/// Not through `signatures_at`: that engine reads a *rendering*, and a macro is expanded there (`ADD(1, |)` is
/// `((1) + ())`), so the call does not exist in it. `Session::macro_signature_at` is the written-text query, and it
/// takes the **file** offset the client's position names.
fn macro_signature_where_marked(source: &str) -> Option<CallSignature> {
    let offset = source.find('|').expect("the fixture marks the cursor");
    let without_marker = source.replace('|', "");
    let session = session_with(&[("/p/a.cpp", &without_marker)]);
    let written = session
        .view_of_the_file(std::path::Path::new("/p/a.cpp"))
        .expect("the file is held");
    session.macro_signature_at(
        &written,
        cpp_code_analysis::file::coordinates::FileOffset::new(offset),
    )
}

/// **A function-like macro is a call, and its parameters are written by the `#define`.**
///
/// The signature engine reads the **rendering**, where a macro is already expanded: `ADD(1, |)` is `((1) + ())`
/// there and there is no call left to describe. So the answer has to come from the file's own text — the text the
/// reader is looking at, macro still in it — and that is what this asks about.
#[test]
fn a_function_like_macro_has_a_signature() {
    let source = "\
#define ADD(a, b) ((a) + (b))
int f() { return ADD(1, |); }
";
    let signature = macro_signature_where_marked(source).expect("a macro call has a signature");
    assert_eq!(signature.label, "ADD(a, b)");
    assert_eq!(signature.parameters.len(), 2, "{:?}", signature.parameters);
    assert_eq!(signature.active_parameter, Some(1));
    assert_eq!(
        signature.parameters[0].1.trim(),
        "a",
        "the parameter names are the macro's own"
    );
}

/// **An object-like macro is not a call.**
#[test]
fn an_object_like_macro_is_not_a_signature() {
    let source = "\
#define LIMIT 10
int f() { return LIMIT|; }
";
    assert!(
        macro_signature_where_marked(source).is_none(),
        "`LIMIT` is not a call"
    );
}

/// **A call of a class is a constructor call, and the constructor's parameters are the signature.**
///
/// `Widget(1, 2)` is a *temporary of `Widget`*, and the popup that matters while the reader types the arguments is the
/// constructor's — the direct-initialization form `Widget w(1, 2)` already answered that way, and the call
/// expression is the same question written as an expression. Reported with a screenshot from
/// `EmmyLuaCodeStyle`: `LuaParser(file, tokens)` and `Widget(1, 2)` showed no signature at all.
#[test]
fn a_call_of_a_class_offers_its_constructors_signature() {
    let source = "\
struct Widget {
    Widget(int width, int height);
};
Widget make() { return Widget(1, |); }
";
    let (_without, signature) = signature_where_marked(source);
    let signature = signature.expect("a call of a class is a constructor call");
    assert_eq!(signature.label, "Widget(int width, int height)");
    assert_eq!(
        signature.active_parameter,
        Some(1),
        "the cursor is in the second argument"
    );
}

/// **A call of a class whose constructors are several and declared in a header.**
///
/// The shape `EmmyLuaCodeStyle` writes: `LuaParser(file, tokens)` with `LuaParser` declared in `lualexer.h` and four
/// constructors, one of them taking the two arguments written. A popup that only answers when there is exactly one
/// constructor answers nothing on the ordinary shape.
/// **A call of a class whose constructors are several and declared in a header.**
///
/// The shape `EmmyLuaCodeStyle` writes: `LuaParser(file, tokens)` with `LuaParser` declared in `luaparser.h` and
/// several constructors, one of them taking the two arguments written. A popup that only answers when there is
/// exactly one constructor answers nothing on the ordinary shape.
#[test]
fn a_call_of_a_class_in_a_header_offers_every_constructor() {
    let header = "\
struct Source { int size; };
struct Tokens { int count; };
struct Widget {
    Widget();
    Widget(Source& source);
    Widget(Source& source, Tokens& tokens);
};
";
    let caller = "\
#include \"widget.h\"
Widget make(Source& source, Tokens& tokens) { return Widget(source, |tokens); }
";
    let offset = caller.find('|').expect("the fixture marks the cursor");
    let without_marker = caller.replace('|', "");
    let session = session_with(&[("/p/widget.h", header), ("/p/a.cpp", &without_marker)]);
    let view = session.view("/p/a.cpp").expect("the file is held");
    let in_the_reading = view
        .reading_offset_of(cpp_code_analysis::file::coordinates::FileOffset::new(
            offset,
        ))
        .expect("the cursor is in the rendering");
    let signatures = session.signatures_at(&view, in_the_reading);
    assert!(
        signatures
            .iter()
            .any(|signature| signature.label.contains("Tokens")),
        "the header declares `Widget(Source&, Tokens&)`, and that is the call: {signatures:?}"
    );
}