mcpls-core 0.6.0

Core library for MCP to LSP protocol translation
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
//! End-to-end tests for MCP protocol implementation.
//!
//! These tests validate the complete MCP protocol flow by spawning the mcpls
//! binary and communicating with it as a real MCP client would.

use anyhow::Result;
use serde_json::json;
use tempfile::TempDir;

use super::mcp_client::McpClient;
use crate::common::test_utils::{rust_analyzer_available, rust_workspace_path};

/// Test the MCP initialize handshake.
///
/// Validates that the server:
/// - Accepts the initialize request
/// - Returns the correct protocol version
/// - Exposes tool capabilities
/// - Provides server information
#[test]
#[ignore = "Requires mcpls binary built"]
fn test_e2e_initialize_handshake() -> Result<()> {
    let mut client = McpClient::spawn()?;

    let response = client.initialize()?;

    assert!(
        response.get("result").is_some(),
        "Response should have 'result' field"
    );

    let result = &response["result"];

    assert_eq!(
        result["protocolVersion"], "2024-11-05",
        "Protocol version should match"
    );

    assert!(
        result["capabilities"]["tools"].is_object(),
        "Should expose tools capability"
    );

    assert_eq!(
        result["serverInfo"]["name"], "mcpls",
        "Server name should be 'mcpls'"
    );

    Ok(())
}

/// Test that a configured `[mcp].title` reaches the real `initialize`
/// response, driving the actual `serve_with` -> `McplsServer::new` ->
/// `get_info` path (#347) rather than constructing `McpConfig` in-process.
#[test]
#[ignore = "Requires mcpls binary built"]
fn test_e2e_initialize_reflects_configured_mcp_title() -> Result<()> {
    let config_path =
        std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("tests/fixtures/mcp_config.toml");

    let mut client = McpClient::spawn_with_args(&[
        "--config",
        config_path
            .to_str()
            .ok_or_else(|| anyhow::anyhow!("Invalid config path"))?,
    ])?;

    let response = client.initialize()?;
    let result = &response["result"];

    assert_eq!(
        result["serverInfo"]["title"], "E2E Custom Title",
        "Configured mcp.title should surface in serverInfo.title"
    );
    assert_eq!(
        result["serverInfo"]["name"], "mcpls",
        "serverInfo.name stays hardcoded regardless of [mcp] config"
    );

    Ok(())
}

/// Test that a configured `[mcp].tool_prefix` reaches the real wiring end to
/// end (#353): `tools/list` exposes only prefixed names, a `tools/call`
/// using the prefixed name reaches the handler, and the same call with the
/// bare (unprefixed) name is rejected as unknown. Unit tests in
/// `mcp::server` already cover the surface exhaustively via
/// `McplsServer::build_tool_router`/`::new` directly -- this is the one
/// test proving the config value actually traverses `serve_with` ->
/// `McplsServer::new` -> the real `ToolRouter`.
#[test]
#[ignore = "Requires mcpls binary built"]
fn test_e2e_tool_prefix_reaches_real_wiring() -> Result<()> {
    let config_path = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
        .join("tests/fixtures/mcp_tool_prefix.toml");

    let mut client = McpClient::spawn_with_args(&[
        "--config",
        config_path
            .to_str()
            .ok_or_else(|| anyhow::anyhow!("Invalid config path"))?,
    ])?;

    client.initialize()?;

    let list_response = client.list_tools()?;
    let names: Vec<&str> = list_response["result"]["tools"]
        .as_array()
        .ok_or_else(|| anyhow::anyhow!("tools/list did not return an array"))?
        .iter()
        .filter_map(|tool| tool["name"].as_str())
        .collect();

    assert!(
        names.contains(&"optics_get_cached_diagnostics"),
        "tools/list should expose the configured prefix: {names:?}"
    );
    assert!(
        !names.contains(&"get_cached_diagnostics"),
        "tools/list should not expose the unprefixed name once a prefix is configured: {names:?}"
    );

    // `get_cached_diagnostics` still fails for a nonexistent path (a file
    // I/O error resolving its URI), but that error is distinct from
    // `ToolRouter`'s "tool not found" -- reaching it proves the prefixed
    // name was dispatched to the real handler, not rejected by routing.
    let prefixed_result = client.call_tool(
        "optics_get_cached_diagnostics",
        &json!({ "file_path": "/nonexistent/file.rs" }),
    );
    if let Err(e) = &prefixed_result {
        assert!(
            !e.to_string().contains("tool not found"),
            "prefixed tool call should reach the handler: {e}"
        );
    }

    let bare_result = client.call_tool(
        "get_cached_diagnostics",
        &json!({ "file_path": "/nonexistent/file.rs" }),
    );
    match bare_result {
        Ok(value) => {
            panic!("bare tool name should be rejected once a prefix is configured, got: {value:?}")
        }
        Err(err) => assert!(err.to_string().contains("tool not found"), "{err}"),
    }

    Ok(())
}

/// Test listing all available MCP tools.
///
/// Validates that:
/// - tools/list returns an array of 16 tools
/// - All expected tool names are present
#[test]
#[ignore = "Requires mcpls binary built"]
fn test_e2e_list_tools() -> Result<()> {
    let mut client = McpClient::spawn()?;
    client.initialize()?;

    let response = client.list_tools()?;

    let tools = response["result"]["tools"]
        .as_array()
        .unwrap_or_else(|| panic!("tools should be an array"));

    assert_eq!(tools.len(), 20, "Should have exactly 20 tools");

    let tool_names: Vec<&str> = tools.iter().filter_map(|t| t["name"].as_str()).collect();

    for expected in &[
        "get_hover",
        "get_definition",
        "get_references",
        "get_diagnostics",
        "rename_symbol",
        "get_completions",
        "get_document_symbols",
        "format_document",
        "workspace_symbol_search",
        "get_code_actions",
        "prepare_call_hierarchy",
        "get_incoming_calls",
        "get_outgoing_calls",
        "get_cached_diagnostics",
        "get_server_logs",
        "get_server_messages",
        "get_signature_help",
        "go_to_implementation",
        "go_to_type_definition",
        "get_inlay_hints",
    ] {
        assert!(tool_names.contains(expected), "Should have {expected} tool");
    }

    Ok(())
}

/// Test that all tools have valid JSON schemas.
///
/// Validates that each tool has:
/// - A name (string)
/// - A description (string)
/// - An input schema (object)
/// - Schema with "object" type
/// - Schema with properties
#[test]
#[ignore = "Requires mcpls binary built"]
fn test_e2e_tool_schemas() -> Result<()> {
    let mut client = McpClient::spawn()?;
    client.initialize()?;

    let response = client.list_tools()?;
    let tools = response["result"]["tools"]
        .as_array()
        .unwrap_or_else(|| panic!("tools should be an array"));

    for tool in tools {
        let tool_name = tool["name"]
            .as_str()
            .unwrap_or_else(|| panic!("Tool should have name field"));

        assert!(
            tool["name"].is_string(),
            "Tool '{tool_name}' should have name as string"
        );

        assert!(
            tool["description"].is_string(),
            "Tool '{tool_name}' should have description as string"
        );

        assert!(
            tool["inputSchema"].is_object(),
            "Tool '{tool_name}' should have inputSchema as object"
        );

        let schema = &tool["inputSchema"];

        assert_eq!(
            schema["type"], "object",
            "Tool '{tool_name}' schema type should be 'object'"
        );

        assert!(
            schema["properties"].is_object(),
            "Tool '{tool_name}' schema should have properties object"
        );
    }

    Ok(())
}

/// Test calling a non-existent tool.
///
/// Validates that the server properly rejects invalid tool calls
/// with an appropriate error response.
#[test]
#[ignore = "Requires mcpls binary built"]
fn test_e2e_invalid_tool_call() -> Result<()> {
    let mut client = McpClient::spawn()?;
    client.initialize()?;

    let result = client.call_tool("non_existent_tool", &json!({}));

    assert!(result.is_err(), "Should return error for non-existent tool");

    if let Err(err) = result {
        let error_msg = format!("{err:?}");
        assert!(
            error_msg.contains("error") || error_msg.contains("Error"),
            "Error message should indicate failure"
        );
    }

    Ok(())
}

/// Test calling a tool with missing required parameters.
///
/// Validates that the server properly validates tool parameters
/// and rejects calls with missing required fields.
#[test]
#[ignore = "Requires mcpls binary built"]
fn test_e2e_tool_call_missing_params() -> Result<()> {
    let mut client = McpClient::spawn()?;
    client.initialize()?;

    let result = client.call_tool("get_hover", &json!({}));

    assert!(
        result.is_err(),
        "Should return error for missing required parameters"
    );

    if let Err(err) = result {
        let error_msg = format!("{err:?}");
        assert!(
            error_msg.contains("error") || error_msg.contains("Error"),
            "Error message should indicate parameter validation failure"
        );
    }

    Ok(())
}

/// Test calling `get_hover` with invalid file path.
///
/// Validates that the server properly handles file path validation
/// and returns appropriate errors for non-existent files.
#[test]
#[ignore = "Requires mcpls binary built"]
fn test_e2e_tool_call_invalid_file() -> Result<()> {
    let mut client = McpClient::spawn()?;
    client.initialize()?;

    let result = client.call_tool(
        "get_hover",
        &json!({
            "file_path": "/nonexistent/path/to/file.rs",
            "line": 1,
            "character": 1
        }),
    );

    assert!(result.is_err(), "Should return error for non-existent file");

    Ok(())
}

/// Test calling `get_definition` with out-of-bounds position.
///
/// Validates that the server handles position validation correctly.
#[test]
#[ignore = "Requires mcpls binary built"]
fn test_e2e_tool_call_invalid_position() -> Result<()> {
    use std::fs;

    let mut client = McpClient::spawn()?;
    client.initialize()?;

    let temp_dir = TempDir::new()?;
    let test_file = temp_dir.path().join("test.rs");
    fs::write(&test_file, "fn main() {}\n")?;

    let result = client.call_tool(
        "get_definition",
        &json!({
            "file_path": test_file.to_string_lossy(),
            "line": 9999,
            "character": 9999
        }),
    );

    // Server should either return error or empty result for out-of-bounds position
    // Both are acceptable behaviors
    if let Ok(response) = result {
        // If successful, result should indicate no definition found
        let result_field = &response["result"];
        // Accept both null/empty results as valid responses
        assert!(
            result_field.is_null() || result_field.is_array() || result_field.is_object(),
            "Should return null or empty result for invalid position"
        );
    }
    // Error response is also acceptable

    Ok(())
}

/// Test the complete workflow: initialize → list → call tool.
///
/// This test validates the typical usage pattern of an MCP client.
#[test]
#[ignore = "Requires mcpls binary built"]
fn test_e2e_complete_workflow() -> Result<()> {
    let mut client = McpClient::spawn()?;

    // Step 1: Initialize
    let init_response = client.initialize()?;
    assert!(init_response.get("result").is_some());

    // Step 2: List tools
    let list_response = client.list_tools()?;
    let tools = list_response["result"]["tools"]
        .as_array()
        .unwrap_or_else(|| panic!("tools should be an array"));
    assert!(!tools.is_empty(), "Should have tools available");

    // Step 3: Verify we can attempt to call a tool (even if it fails due to no LSP)
    // This validates the protocol flow works end-to-end
    let _result = client.call_tool("get_diagnostics", &json!({"file_path": "test.rs"}));
    // We don't assert success here because LSP servers may not be configured
    // The important part is that the protocol flow works

    Ok(())
}

/// Test multiple sequential requests on the same connection.
///
/// Validates that:
/// - The connection remains stable across multiple requests
/// - Request IDs increment correctly
/// - The server handles concurrent operations properly
#[test]
#[ignore = "Requires mcpls binary built"]
fn test_e2e_multiple_requests() -> Result<()> {
    let mut client = McpClient::spawn()?;

    // Multiple initialize calls should work (idempotent)
    let response1 = client.initialize()?;
    assert!(response1.get("result").is_some());

    let response2 = client.list_tools()?;
    assert!(response2.get("result").is_some());

    let response3 = client.list_tools()?;
    assert!(response3.get("result").is_some());

    // Responses should have different IDs
    assert_ne!(
        response1.get("id"),
        response2.get("id"),
        "Different requests should have different IDs"
    );
    assert_ne!(
        response2.get("id"),
        response3.get("id"),
        "Different requests should have different IDs"
    );

    Ok(())
}

/// Test that mcpls exits promptly on `SIGTERM` while the client's stdin
/// write end is still open (regression test for #308).
///
/// The MCP stdio transport is backed by `tokio::io::stdin()`, which parks an
/// uncancellable blocking-pool thread in a raw `read()` syscall. Without the
/// `std::process::exit` fix in `mcpls-cli`'s `main`, `#[tokio::main]`'s
/// runtime-shutdown wait for that thread would hang indefinitely as long as
/// the client (this test, via `McpClient`) keeps stdin's write end open.
///
/// Sending `SIGTERM` immediately after the handshake completes (no
/// artificial delay) also touches the tail of #318's window — the narrow gap
/// between `run_stdio`'s two `select!` blocks — but only weakly: signaling
/// this soon after `initialize()` returns reproduced the pre-fix bug in just
/// 1/15 runs, since the client-side I/O latency before the `kill` command
/// even runs dwarfs that gap. `test_e2e_sigterm_exits_promptly_during_handshake_wait`
/// below is the reliable reproducer for #318 (5/5 against pre-fix code).
#[test]
#[cfg(unix)]
#[ignore = "Requires mcpls binary built"]
fn test_e2e_sigterm_exits_promptly_while_client_stdin_open() -> Result<()> {
    let mut client = McpClient::spawn()?;
    client.initialize()?;

    // No delay here is intentional: `run_stdio` now registers its SIGTERM
    // handler before awaiting the handshake at all (see #318), so the signal
    // is raced against the handshake/select loop from the moment the
    // process starts. Sending SIGTERM immediately after `initialize()`
    // returns exercises the narrowest part of that window instead of
    // masking it behind an artificial delay.
    let pid = client.pid();
    let status = std::process::Command::new("kill")
        .args(["-TERM", &pid.to_string()])
        .status()?;
    assert!(
        status.success(),
        "failed to send SIGTERM to mcpls (pid {pid})"
    );

    let deadline = std::time::Instant::now() + std::time::Duration::from_secs(5);
    loop {
        if let Some(exit_status) = client.try_wait()? {
            // Distinguishes a graceful `process::exit(0)` from the process
            // being killed outright by the default SIGTERM disposition
            // (e.g. if the signal handler failed to register) -- the latter
            // would also make `try_wait` return `Some`, but with no LSP
            // shutdown having run. On Unix, `code()` is `None` for
            // signal-termination, so this one assertion covers both.
            assert_eq!(
                exit_status.code(),
                Some(0),
                "mcpls should exit with status 0 via its own shutdown path, not be killed \
                 by the default SIGTERM disposition (issue #308 regression)"
            );
            return Ok(());
        }
        assert!(
            std::time::Instant::now() < deadline,
            "mcpls did not exit within 5s of SIGTERM while the client's stdin write end \
             was still open (issue #308 regression)"
        );
        std::thread::sleep(std::time::Duration::from_millis(50));
    }
}

/// Test that mcpls exits promptly on `SIGTERM` sent *before* the client ever
/// sends the `initialize` request -- i.e. strictly during the MCP handshake
/// wait itself (regression test for #318).
///
/// This targets the actual bug in #318 directly: pre-fix, `run_stdio`
/// registered its `SIGTERM` handler only *after* `mcp_server.serve(..)`
/// resolved, so any signal arriving while `serve(..)` was still awaiting the
/// client's `initialize` request -- which can be an arbitrarily long wait in
/// real usage -- fell through to the OS's default disposition (immediate
/// kill, no graceful shutdown, no LSP cleanup). Sending `SIGTERM`
/// immediately after spawning, before writing anything to the child's
/// stdin, reliably lands inside that wait rather than racing the much
/// narrower post-handshake gap that
/// `test_e2e_sigterm_exits_promptly_while_client_stdin_open` exercises.
#[test]
#[cfg(unix)]
#[ignore = "Requires mcpls binary built"]
fn test_e2e_sigterm_exits_promptly_during_handshake_wait() -> Result<()> {
    let mut client = McpClient::spawn()?;

    // A brief sleep before signaling clears the unrelated, unfixable gap
    // between `fork`/`exec` and the point where *any* process code (the
    // runtime init that precedes even the fixed `ShutdownSignal::new()`)
    // has run -- the OS applies the default disposition until then no
    // matter what the binary does, so signaling with zero delay would fail
    // even against the fix and wouldn't be exercising #318 at all. 50ms is
    // far below the 5s deadline below and well within the handshake wait,
    // since `initialize()` is deliberately never called: the child is left
    // parked inside `mcp_server.serve(..)`, waiting to read the client's
    // first request.
    std::thread::sleep(std::time::Duration::from_millis(50));

    let pid = client.pid();
    let status = std::process::Command::new("kill")
        .args(["-TERM", &pid.to_string()])
        .status()?;
    assert!(
        status.success(),
        "failed to send SIGTERM to mcpls (pid {pid})"
    );

    let deadline = std::time::Instant::now() + std::time::Duration::from_secs(5);
    loop {
        if let Some(exit_status) = client.try_wait()? {
            assert_eq!(
                exit_status.code(),
                Some(0),
                "mcpls should exit with status 0 via its own shutdown path even when SIGTERM \
                 arrives before the MCP handshake completes, not be killed by the default \
                 SIGTERM disposition (issue #318 regression)"
            );
            return Ok(());
        }
        assert!(
            std::time::Instant::now() < deadline,
            "mcpls did not exit within 5s of SIGTERM sent before the handshake completed \
             (issue #318 regression)"
        );
        std::thread::sleep(std::time::Duration::from_millis(50));
    }
}

// ---------------------------------------------------------------------------
// #325: workspace resource-limit config, enforced through the real
// `serve()`/`serve_with()` startup path.
// ---------------------------------------------------------------------------

/// Spawns the real `mcpls` binary against a config naming a real
/// rust-analyzer server for `tests/fixtures/rust_workspace`, with
/// `[workspace]` extended by `extra_workspace_toml` (e.g. `max_documents = 3`).
///
/// This is what makes the resulting tests exercise the actual wiring in
/// `crates/mcpls-core/src/lib.rs`'s `serve_with` (`ServerConfig::load_from`
/// -> `WorkspaceConfig::resource_limits()` -> `Translator::with_resource_limits`)
/// rather than a hand-copied reconstruction of it. The returned `TempDir`
/// must be kept alive for as long as `McpClient`; it's only needed at
/// startup (the config file is read once), but dropping it early is
/// needless risk for no benefit.
fn spawn_mcpls_with_workspace_config(extra_workspace_toml: &str) -> Result<(TempDir, McpClient)> {
    let workspace_path = rust_workspace_path();
    let config_dir = TempDir::new()?;
    let config_path = config_dir.path().join("mcpls.toml");
    let toml_content = format!(
        r#"
        [workspace]
        roots = ["{}"]
        {extra_workspace_toml}

        [[lsp_servers]]
        language_id = "rust"
        command = "rust-analyzer"
        args = []
        file_patterns = ["**/*.rs"]
        "#,
        workspace_path.to_string_lossy().replace('\\', "\\\\")
    );
    std::fs::write(&config_path, toml_content)?;

    let mut client = McpClient::spawn_with_args(&[
        "--config",
        config_path
            .to_str()
            .ok_or_else(|| anyhow::anyhow!("Invalid config path"))?,
    ])?;
    client.initialize()?;

    Ok((config_dir, client))
}

fn hover_args(path: &std::path::Path) -> serde_json::Value {
    json!({
        "file_path": path.to_string_lossy(),
        "line": 1,
        "character": 1,
    })
}

/// Calls `get_hover` on `path`, retrying while the error is
/// `Error::ServerInitializing`/`WorkspaceServersInitializing` (message
/// contains "initializing") -- the transient state before rust-analyzer's
/// background `initialize` handshake (`spawn_lsp_servers_background` in
/// `lib.rs`) has completed and it registers with the translator. This is the
/// only rust-analyzer-readiness state that can affect the calls below:
/// opening a document happens in `prepare_gated_document` *before* the
/// capability-gated LSP round trip (`bridge/translator/routing.rs`), so
/// whether rust-analyzer has finished *indexing* the workspace never affects
/// whether a document is counted against `max_documents`/`max_file_size`.
fn call_hover_past_server_init(
    client: &mut McpClient,
    path: &std::path::Path,
    deadline: std::time::Instant,
) -> Result<serde_json::Value> {
    loop {
        match client.call_tool("get_hover", &hover_args(path)) {
            Err(e) if e.to_string().contains("initializing") => {
                assert!(
                    std::time::Instant::now() < deadline,
                    "rust-analyzer never finished initializing: {e}"
                );
                std::thread::sleep(std::time::Duration::from_millis(200));
            }
            other => return other,
        }
    }
}

/// #325/#495: end-to-end proof that `workspace.max_documents`, set in a real
/// `mcpls.toml`, is enforced by `DocumentTracker` through the actual
/// `serve()`/`serve_with()` startup path (`main` -> `serve` -> `serve_with`
/// -> `Translator::with_resource_limits`), not an in-process reconstruction
/// of that wiring.
///
/// `DocumentTracker::open` evicts the least-recently-used unlocked document
/// (sending `textDocument/didClose` to the LSP server) instead of rejecting
/// once the limit is reached (see `crates/mcpls-core/src/bridge/state.rs`),
/// so this asserts the cap is a real bound, not a ceiling: every open beyond
/// the configured limit must still succeed, crossing the boundary more than
/// once, and a document opened before the limit was first crossed (now
/// long evicted) must remain re-openable afterward.
#[test]
#[ignore = "Requires mcpls binary built and rust-analyzer installed"]
fn test_e2e_max_documents_config_enforced() -> Result<()> {
    if !rust_analyzer_available() {
        eprintln!("Skipping: rust-analyzer not available");
        return Ok(());
    }

    let max_documents = 3;
    let workspace_path = rust_workspace_path();
    let (_config_dir, mut client) =
        spawn_mcpls_with_workspace_config(&format!("max_documents = {max_documents}"))?;

    // At least two more real, distinct files than the configured limit, so
    // opening them one by one crosses the boundary set in TOML more than
    // once, proving eviction repeats rather than firing only for the very
    // first document past the limit.
    let files = [
        workspace_path.join("src/lib.rs"),
        workspace_path.join("src/types.rs"),
        workspace_path.join("src/functions.rs"),
        workspace_path.join("extras/untouched.rs"),
        workspace_path.join("extras/bad_format.rs"),
    ];
    assert!(
        files.len() > max_documents + 1,
        "fixture must provide at least two more files than the configured limit to \
         exercise eviction repeatedly, not just once"
    );

    let deadline = std::time::Instant::now() + std::time::Duration::from_secs(30);
    for (i, path) in files.iter().enumerate() {
        let result = call_hover_past_server_init(&mut client, path, deadline);
        assert!(
            result.is_ok(),
            "opening document {} of {} must succeed: the cap is a real bound that evicts \
             the least-recently-used document, not a ceiling that wedges the session once \
             reached; got: {:?}",
            i + 1,
            files.len(),
            result.err()
        );
    }

    // The first document opened is now the least recently used and has long
    // since been evicted from the tracker. Re-opening it must still succeed,
    // proving eviction actually released the tracker slot (and closed the
    // document on the LSP server) instead of leaving it in a broken,
    // half-tracked state.
    let result = call_hover_past_server_init(&mut client, &files[0], deadline);
    assert!(
        result.is_ok(),
        "re-opening the first (evicted) document must succeed: {:?}",
        result.err()
    );

    Ok(())
}

/// #325: end-to-end proof that `workspace.max_file_size`, set in a real
/// `mcpls.toml`, is enforced by `DocumentTracker` through the real
/// `serve()`/`serve_with()` startup path. Companion to
/// `test_e2e_max_documents_config_enforced`, covering the other
/// `[workspace]` resource-limit field #325 asked for.
#[test]
#[ignore = "Requires mcpls binary built and rust-analyzer installed"]
fn test_e2e_max_file_size_config_enforced() -> Result<()> {
    if !rust_analyzer_available() {
        eprintln!("Skipping: rust-analyzer not available");
        return Ok(());
    }

    let workspace_path = rust_workspace_path();
    // Every real fixture file is larger than 1 byte, so this deterministically
    // rejects the very first document opened, regardless of which one.
    let (_config_dir, mut client) = spawn_mcpls_with_workspace_config("max_file_size = 1")?;

    let lib_rs = workspace_path.join("src/lib.rs");
    let deadline = std::time::Instant::now() + std::time::Duration::from_secs(30);
    let result = call_hover_past_server_init(&mut client, &lib_rs, deadline);
    match result {
        Err(e) => assert!(
            e.to_string().contains("file size limit exceeded"),
            "expected a FileSizeLimitExceeded error, got: {e}"
        ),
        Ok(_) => panic!("a file exceeding the configured max_file_size must be rejected"),
    }

    Ok(())
}