mcpls rust-bridge.instructions.md

Type safety

Position types (line, column) must be distinct newtypes, not bare u32. The MCP convention (1-based) and the LSP convention (0-based) must be expressed in the type system so that passing an MCP position directly to an LSP call is a compile error.

Protocol message variants must be an enum, not a string-matched dispatch. Matching on "textDocument/hover" strings is fragile; a closed enum of known methods makes unhandled cases visible at compile time and exhaustiveness-checked.

InboundMessage and similar enums that may gain variants in future protocol versions must be #[non_exhaustive] so downstream crates are not broken by additions.

Document state

Caching document content alongside a filesystem signature (mtime + size) prevents stale reads after external edits. On every access, stat the file and compare against the cached signature; re-read and re-notify the LSP server on mismatch.

Stat and read must use the same file handle to close the TOCTOU window. Open the file once with tokio::fs::File::open, call .metadata().await on the handle, then read through the same handle. A separate tokio::fs::metadata call before read_to_string leaves a window where an atomic rename can change the file between the two calls.

Document version numbers must be strictly monotone per URI. On overflow, reset to 1 rather than saturating — after didClose/didOpen the server treats the document as fresh and the version value is irrelevant to continuity.

Diagnostics pipeline

When a feature draws from multiple independent sources (pull request + push cache), fetch them concurrently with tokio::try_join! or tokio::join!. Awaiting them sequentially serialises work that has no data dependency.

A cache miss must be distinguishable from an empty result. Returning Vec::new() for both "no errors" and "not yet analysed" is ambiguous to callers. Use an Option<Vec> or a dedicated status type to express the difference.

Deduplication keys should prefer structured fields (error code) over free-form message text. When a code is present, key on (range, severity, code). The doc comment must describe the actual key — a mismatch between the comment and the implementation causes silent behavioural bugs.