fix(#102): handle external file changes via stat-resync, didChangeWatchedFiles, and a populated diagnostics cache

[flukejones]

Closes #102.

Four commits, each independently passing tests/clippy/fmt:

1. fix(bridge): re-sync DocumentTracker on external file changes — ensure_open now stats the file on every call and, on signature mismatch, sends textDocument/didClose followed by a bumped-version textDocument/didOpen to keep the LSP server in sync with disk. Fixes stale results from every per-file MCP tool (get_hover, get_definition, get_references, get_document_symbols, get_diagnostics, get_completions, get_code_actions, format_document, rename_symbol, call-hierarchy) after edits made outside mcpls (git stash/checkout, the MCP host's own Edit/Write tools, formatters, code generators). Works for every configured LSP, including those that don't register workspace/didChangeWatchedFiles (e.g. zls).

2. feat(lsp): forward workspace/didChangeWatchedFiles to LSP servers — declares workspace.didChangeWatchedFiles.dynamic_registration: true and relative_pattern_support: true, handles inbound client/registerCapability/client/unregisterCapability, and runs a per-server notify filesystem watcher that forwards matched events as workspace/didChangeWatchedFiles. Keeps the LSP server's workspace index live (the half of the bug that survives stat-on-access) for servers that register watchers (rust-analyzer, gopls, pyright, typescript-language-server, clangd). The transport now distinguishes server-to-client requests from responses (InboundMessage::Request); previously such requests were silently misclassified as responses. New runtime dependency: notify (+ globset for compiled glob matching).

3. feat(bridge): populate NotificationCache, add diagnostics_mode — wires publishDiagnostics/logMessage/showMessage into the NotificationCache (the cache existed but was never populated in production — every notification was dropped). Adds workspace.diagnostics_mode config option:

   • pull — only textDocument/diagnostic. Misses rust-analyzer's flycheck output.
   • cached — only the now-populated push cache.
   • hybrid — pull + cached, deduplicated. Default.

4. refactor(bridge): tighter dedup for hybrid diagnostics merge — keys on (range, severity, code) when a code is present (so rust-analyzer's DocItem vs types::DocItem qualifier-only duplicates collapse), and falls back to a path-qualifier-stripped message comparison when code is None. Saves ~30–50% of token output in compile-error-heavy phases without dropping legitimately-distinct errors that share a span.

Design recorded in docs/adr/0001-external-file-changes.md.

Verified end-to-end

User report from a real workflow before/after:

Probe	Before	After
workspace_symbol_search("BlockItem")	line 308 (frozen at session start)	line 147 (current disk state)
get_diagnostics(y_adjust.rs)	[] despite 5 cargo errors (file not LSP-opened)	5 real E0599 errors at lines 87, 94, 108, 120
get_cached_diagnostics(y_adjust.rs)	[] (never populated)	the same 5 errors

The "must Read first to trigger didOpen" workaround is no longer needed.

Test plan

• 342 unit tests (320 baseline + 22 new across file_watcher, state-resync, dedup, diagnostics_mode serde)
• 3 new ignored integration tests under real rust-analyzer:
  • test_ensure_open_resyncs_after_external_edit — primes a query, overwrites the file on disk, asserts the next query reflects the new symbols.
  • test_lsp_server_installs_watcher_registration — LspServer::spawn completes when rust-analyzer sends client/registerCapability, exercising the transport Request variant + dispatcher + FileWatcher::register.
  • test_notification_cache_populates_from_publish_diagnostics — verifies get_cached_diagnostics reflects RA's flycheck output after the pump task delivers the push notification.
• cargo clippy --workspace --all-targets --all-features -- -D warnings clean
• cargo +nightly fmt --check clean

🤖 Generated with Claude Code

[flukejones]

I just realised this probably really needs a token generation count...

[Copilot]

Pull request overview

This PR fixes #102 by keeping mcpls and underlying LSP servers consistent with on-disk edits made outside mcpls, adds workspace/didChangeWatchedFiles forwarding via a per-server filesystem watcher, and makes diagnostics usable by populating/pulling/merging through a configurable diagnostics_mode.

Changes:

• Re-sync tracked documents on external edits (stat-on-access + didClose/didOpen) to prevent stale per-file tool results.
• Add server-to-client JSON-RPC request handling plus workspace/didChangeWatchedFiles dynamic registration and a notify-based watcher to keep workspace indexes fresh.
• Populate NotificationCache from LSP notifications and add workspace.diagnostics_mode with hybrid dedup.

Reviewed changes

Copilot reviewed 17 out of 18 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
examples/mcpls.toml	Documents new workspace.diagnostics_mode config.
docs/adr/0001-external-file-changes.md	ADR capturing the external-change handling design and tradeoffs.
crates/mcpls-core/tests/integration/rust_analyzer_tests.rs	Adds ignored rust-analyzer integration regressions for resync, watcher registration, and diagnostics cache.
crates/mcpls-core/src/lsp/types.rs	Introduces InboundMessage::Request and tightens notification parsing contract.
crates/mcpls-core/src/lsp/transport.rs	Correctly classifies inbound JSON-RPC messages as request/response/notification.
crates/mcpls-core/src/lsp/mod.rs	Exposes watcher/request types needed by lifecycle/client.
crates/mcpls-core/src/lsp/lifecycle.rs	Wires watcher + request dispatcher into server spawn/init; exposes notification receiver.
crates/mcpls-core/src/lsp/file_watcher.rs	Implements notify-backed watcher and LSP event forwarding with glob matching/coalescing.
crates/mcpls-core/src/lsp/client.rs	Adds server-to-client request forwarding and response sending in the message loop.
crates/mcpls-core/src/lib.rs	Pumps LSP notifications into NotificationCache and wires diagnostics mode from config.
crates/mcpls-core/src/config/mod.rs	Adds workspace.diagnostics_mode enum + serde/default behavior and tests.
crates/mcpls-core/src/bridge/translator.rs	Implements pull/cached/hybrid diagnostics sourcing and hybrid dedup logic.
crates/mcpls-core/src/bridge/state.rs	Adds file signatures + resync logic in DocumentTracker::ensure_open.
crates/mcpls-core/src/bridge/mod.rs	Re-exports SyncSignature.
crates/mcpls-core/Cargo.toml	Adds notify + globset runtime deps.
Cargo.toml	Adds workspace-level notify + globset versions.
Cargo.lock	Locks new dependency graph for watcher functionality.
CHANGELOG.md	Documents the new watcher support, resync behavior, and diagnostics mode.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The spawn docstring says this returns an error “if any workspace root cannot be watched”, but the implementation only logs a warning and continues when watcher.watch(root, ...) fails. Either update the docs to reflect the non-fatal/partial-watch behavior, or change the implementation to fail (or at least error) when no roots could be watched.

Suggested change

	for root in &workspace_roots {
	if let Err(e) = watcher.watch(root, RecursiveMode::Recursive) {
	warn!("file watcher: failed to watch {}: {e}", root.display());
	}
	}
	let mut watched_root_count = 0usize;
	for root in &workspace_roots {
	match watcher.watch(root, RecursiveMode::Recursive) {
	Ok(()) => watched_root_count += 1,
	Err(e) => {
	warn!("file watcher: failed to watch {}: {e}", root.display());
	}
	}
	}
	if !workspace_roots.is_empty() && watched_root_count == 0 {
	return Err(Error::Transport(
	"file watcher: failed to watch any workspace roots".to_string(),
	));
	}

[Copilot]

set_synced_signature is called before the first didOpen is successfully sent. If textDocument/didOpen fails (transient transport issue), the document remains tracked with a matching signature, so subsequent ensure_open calls will short-circuit and never retry the didOpen, leaving the LSP server out of sync. Consider only recording synced_signature (and/or inserting the document) after didOpen succeeds, or roll back the tracked state / set the signature back to UNKNOWN on failure so the next call retries.

[bug-ops]

Validation pass — 2 blocking issues + 1 CI break.

deny.toml — notify 8.2.0 is licensed under CC0-1.0, which is absent from the allow list. cargo deny check licenses will fail on first CI run. Add "CC0-1.0" to the allow list.

Other findings inline.