java-functional-lsp 0.9.12__tar.gz → 0.9.14__tar.gz

{java_functional_lsp-0.9.12 → java_functional_lsp-0.9.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: java-functional-lsp
-Version: 0.9.12
+Version: 0.9.14
 Summary: Java LSP server enforcing functional programming best practices — null safety, immutability, no exceptions
 Project-URL: Homepage, https://github.com/aviadshiber/java-functional-lsp
 Project-URL: Repository, https://github.com/aviadshiber/java-functional-lsp

{java_functional_lsp-0.9.12 → java_functional_lsp-0.9.14}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "java-functional-lsp"
-version = "0.9.12"
+version = "0.9.14"
 description = "Java LSP server enforcing functional programming best practices — null safety, immutability, no exceptions"
 readme = "README.md"
 license = { text = "MIT" }

{java_functional_lsp-0.9.12 → java_functional_lsp-0.9.14}/src/java_functional_lsp/__init__.py

@@ -1,3 +1,3 @@
 """java-functional-lsp: A Java LSP server enforcing functional programming best practices."""
 
-__version__ = "0.9.12"
+__version__ = "0.9.14"

{java_functional_lsp-0.9.12 → java_functional_lsp-0.9.14}/src/java_functional_lsp/proxy.py

@@ -29,6 +29,7 @@ _START_RETRY_COOLDOWN = 300.0  # seconds — retry jdtls startup after transient
 DEFAULT_JVM_MAX_HEAP = "4g"
 _STDERR_LINE_MAX = 1000
 _MAX_EXPANDED_GROUPS: int = 5  # hard cap on concurrent Maven group workspace folders (prevents jdtls OOM)
+_WORKSPACE_CACHE_MAX_SIZE: int = 10  # default LRU cap — override via {"cache": {"maxWorkspaces": N}}
 
 # Default jdtls initialization settings.  Sent via initializationOptions.settings
 # so they apply BEFORE the Maven import scan (didChangeConfiguration is too late).
@@ -563,6 +564,87 @@ def _compute_module_diff(
     return (diff, current)
 
 
+def _dir_mtime(path: Path) -> float:
+    """Return ``st_mtime`` of *path*, or ``float('inf')`` on any OSError.
+
+    Returning infinity on error sorts the directory as the *newest* entry,
+    so stat-inaccessible directories are conservatively kept rather than
+    silently evicted.
+    """
+    try:
+        return path.stat().st_mtime
+    except OSError:
+        return float("inf")
+
+
+def _parse_max_workspaces(config: Mapping[str, Any] | None) -> int:
+    """Parse and validate ``cache.maxWorkspaces`` from the project config.
+
+    Returns *_WORKSPACE_CACHE_MAX_SIZE* when the key is absent, when the value
+    cannot be converted to ``int``, or when the result is not positive.  Logs a
+    warning in each error case so the user can diagnose the misconfiguration.
+    """
+    raw = (config or {}).get("cache", {}).get("maxWorkspaces")
+    if raw is None:
+        return _WORKSPACE_CACHE_MAX_SIZE
+    try:
+        value = int(raw)
+    except (TypeError, ValueError):
+        logger.warning(
+            "jdtls: invalid cache.maxWorkspaces %r — using default %d",
+            raw,
+            _WORKSPACE_CACHE_MAX_SIZE,
+        )
+        return _WORKSPACE_CACHE_MAX_SIZE
+    if value <= 0:
+        logger.warning(
+            "jdtls: cache.maxWorkspaces must be >= 1, got %d — using default %d",
+            value,
+            _WORKSPACE_CACHE_MAX_SIZE,
+        )
+        return _WORKSPACE_CACHE_MAX_SIZE
+    return value
+
+
+def _evict_lru_workspaces(cache_root: Path, *, max_size: int = _WORKSPACE_CACHE_MAX_SIZE) -> None:
+    """Evict least-recently-used jdtls workspace directories when count exceeds *max_size*.
+
+    Implements Caffeine's ``maximumSize`` eviction policy for a filesystem cache.
+    Directories are ordered by ``st_mtime`` (last modification time), which is a
+    reliable proxy for last-used time because jdtls always writes to its workspace
+    on startup.  On macOS APFS (``noatime`` default) ``atime`` is not updated on
+    reads, so ``mtime`` is used exclusively.
+
+    The *max_size* most-recently-modified real directories are kept; the rest are
+    removed.  Dotfiles (e.g. ``.version``), symlinks, and non-directory entries
+    are excluded from the eviction candidates.
+
+    A directory whose ``stat()`` raises ``OSError`` is treated as the *newest*
+    entry (``float('inf')`` mtime) so it is conservatively kept.
+
+    Runs in the executor thread (``_blocking_startup``) — never blocks the event loop.
+
+    Users can tune the cap via ``.java-functional-lsp.json``:
+    ``{"cache": {"maxWorkspaces": 20}}``
+    """
+    if not cache_root.is_dir():
+        return
+    try:
+        dirs = [d for d in cache_root.iterdir() if d.is_dir() and not d.is_symlink() and not d.name.startswith(".")]
+    except OSError as e:
+        logger.warning("jdtls: cannot scan cache root for eviction: %s", e)
+        return
+    if len(dirs) <= max_size:
+        return
+    dirs.sort(key=_dir_mtime, reverse=True)  # newest first
+    for stale in dirs[max_size:]:
+        try:
+            shutil.rmtree(stale)
+            logger.info("jdtls: evicted workspace cache %s (LRU)", stale.name)
+        except OSError as e:
+            logger.warning("jdtls: failed to evict workspace cache %s: %s", stale.name, e)
+
+
 def _wipe_data_dir(data_dir: Path) -> None:
     """Remove *data_dir* so the next jdtls startup gets a clean cold start.
 
@@ -793,6 +875,8 @@ class JdtlsProxy:
 
         def _blocking_startup() -> tuple[dict[str, str], str | None]:
             _clear_cache_on_version_change(cache_root)
+            max_workspaces = _parse_max_workspaces(config)
+            _evict_lru_workspaces(cache_root, max_size=max_workspaces)
             return build_jdtls_env(), _find_lombok_jar(config)
 
         loop = asyncio.get_running_loop()

{java_functional_lsp-0.9.12 → java_functional_lsp-0.9.14}/src/java_functional_lsp/server.py

@@ -13,6 +13,7 @@ import os
 import re
 import sys
 import time
+from collections import OrderedDict
 from collections.abc import Coroutine
 from pathlib import Path
 from typing import Any
@@ -20,7 +21,7 @@ from typing import Any
 from lsprotocol import types as lsp
 from lsprotocol.converters import get_converter
 from pygls.lsp.server import LanguageServer
-from pygls.uris import to_fs_path
+from pygls.uris import from_fs_path, to_fs_path
 
 from .analyzers.base import Analyzer, Severity, get_parser, is_excluded, is_suppressed
 from .analyzers.base import Diagnostic as LintDiagnostic
@@ -62,6 +63,34 @@ _JDTLS_SKIP_CLIENTS = ("IntelliJ", "JetBrains")
 #: go-to-definition, references, etc.
 _converter = get_converter()
 
+# Cap on _session_opened_uris: a session navigating many files still bounds memory.
+# 4096 comfortably covers even aggressive monorepo navigation.
+_MAX_OPENED_URIS = 4096
+
+
+def _normalize_uri(uri: str) -> str:
+    """Canonicalize a file:// URI so equivalent paths compare equal.
+
+    Round-trips through pygls.uris to normalize URL encoding differences
+    (``%20`` vs literal space, ``%3A`` vs ``:``, trailing slashes, double
+    slashes) between what the client sends and what jdtls echoes back.
+
+    Non-file URIs (``jdt://``, ``untitled://``, etc.) are returned unchanged —
+    they're never stored in ``_session_opened_uris`` so they'll fall through the gate
+    regardless. Case-insensitive filesystems (macOS HFS+, NTFS) are not
+    normalized here: attempting that would require ``Path.resolve()``, which
+    would stat the filesystem and follow symlinks — too expensive for a hot
+    path that runs on every jdtls publish. On Windows, drive-letter case
+    (``C:`` vs ``c:``) is similarly not normalized.
+    """
+    if not uri.startswith("file:"):
+        return uri
+    fs = to_fs_path(uri)
+    if fs is None:
+        return uri
+    normalized = from_fs_path(fs)
+    return normalized if normalized is not None else uri
+
 
 class JavaFunctionalLspServer(LanguageServer):
     def __init__(self) -> None:
@@ -76,6 +105,33 @@ class JavaFunctionalLspServer(LanguageServer):
         self._skip_jdtls: bool = False
         self._skip_jdtls_registration: bool = False
         self._init_generation: int = 0
+        # URIs the client has opened at least once this session (normalized form).
+        # Jdtls indexes the whole workspace and publishes diagnostics for files the
+        # client never touched; we only republish for URIs present here so unrelated
+        # modules don't flood the client. Cumulative (not cleared on didClose) to
+        # survive the async race between didClose and late jdtls publishes.
+        # Bounded LRU: insertion-ordered, oldest evicted on overflow so a long
+        # session navigating many files can't grow the set unboundedly.
+        # Reset on initialize.
+        self._session_opened_uris: OrderedDict[str, None] = OrderedDict()
+
+    def _record_opened(self, uri: str) -> None:
+        """Record *uri* as opened this session, evicting the oldest entry at cap.
+
+        Stores the normalized form so gate lookups in ``_on_jdtls_diagnostics``
+        can use a fast raw-first check without redundant normalization.
+        """
+        uri = _normalize_uri(uri)
+        if uri in self._session_opened_uris:
+            self._session_opened_uris.move_to_end(uri)
+            return
+        self._session_opened_uris[uri] = None
+        # Size check uses > so the dict stabilises at exactly _MAX_OPENED_URIS
+        # entries after the pop: we insert first (reaching MAX+1 momentarily),
+        # then evict. The transient overshoot is invisible to other callers
+        # because asyncio is single-threaded and no await intervenes here.
+        if len(self._session_opened_uris) > _MAX_OPENED_URIS:
+            self._session_opened_uris.popitem(last=False)
 
     def _on_jdtls_diagnostics(self, uri: str, diagnostics: list[Any]) -> None:
         """Called when jdtls publishes diagnostics — merge with custom and re-publish.
@@ -108,10 +164,25 @@ class JavaFunctionalLspServer(LanguageServer):
                     # First READY transition only — subsequent diagnostics for the same
                     # module are no-ops to avoid spawning O(files) redundant tasks.
                     _fire_and_forget(_apply_module_diff(self._proxy, module_uri))
+        # Only republish for files the client has opened at any point this
+        # session (cumulative). Jdtls scans the whole workspace; without this
+        # guard, diagnostics for 200+ unrelated modules leak out as
+        # <new-diagnostics> tags (see #71). Non-file URIs (jdt://, untitled://,
+        # etc.) are never recorded by _record_opened so they're dropped here.
+        #
+        # Two-phase lookup: check the raw URI first (O(1), no allocation) since
+        # jdtls typically echoes URIs in the same form as the client — the fast
+        # path avoids the to_fs_path/from_fs_path round-trip on every publish.
+        # Fall back to the normalized form only on a miss to handle encoding
+        # mismatches (e.g., client sends literal space, jdtls echoes %20).
+        if uri not in self._session_opened_uris and _normalize_uri(uri) not in self._session_opened_uris:
+            return
         try:
             _analyze_and_publish(uri)
         except FileNotFoundError:
-            pass  # Virtual jdtls file (e.g., decompiled source in jdtls-data); skip silently.
+            # The file was in the opened-URIs set but vanished from disk
+            # between didOpen and this late jdtls publish. Benign.
+            pass
         except Exception as e:
             logger.error("Error re-publishing diagnostics for %s: %s", uri, e)
 
@@ -298,6 +369,24 @@ def _jdtls_raw_to_lsp_diagnostics(raw_diagnostics: list[Any]) -> list[lsp.Diagno
 
 _MAX_PATTERN_LENGTH = 500  # Cap regex length to mitigate ReDoS from pathological patterns
 
+_M2E_SOURCES: frozenset[str] = frozenset({"org.eclipse.m2e"})
+_M2E_MESSAGE_PATTERNS: re.Pattern[str] = re.compile(
+    r"Plugin execution not covered by lifecycle configuration"
+    r"|The project cannot be built until its prerequisite"
+    r"|Failed to execute mojo"
+)
+
+
+def _is_m2e_marker(diag: dict[str, Any]) -> bool:
+    """Return True if the diagnostic is an Eclipse/M2E lifecycle marker (not a Java error)."""
+    if str(diag.get("code", "")) == "0":
+        return True
+    if diag.get("source", "") in _M2E_SOURCES:
+        return True
+    if _M2E_MESSAGE_PATTERNS.search(diag.get("message", "")):
+        return True
+    return False
+
 
 def _compile_user_patterns(config: dict[str, Any]) -> list[re.Pattern[str]]:
     """Compile user-defined suppressJdtlsPatterns from config."""
@@ -346,7 +435,9 @@ def _run_analysis(source: str, uri: str) -> list[lsp.Diagnostic]:
     if server._proxy.is_available:
         try:
             raw = server._proxy.get_cached_diagnostics(uri)
-            raw = [d for d in raw if not _is_jdtls_suppressed(d, server._user_suppress_patterns)]
+            raw = [
+                d for d in raw if not _is_m2e_marker(d) and not _is_jdtls_suppressed(d, server._user_suppress_patterns)
+            ]
             jdtls_diags = _jdtls_raw_to_lsp_diagnostics(raw)
         except Exception as e:
             logger.warning("jdtls diagnostic processing failed for %s: %s", uri, e)
@@ -390,6 +481,7 @@ def on_initialize(params: lsp.InitializeParams) -> lsp.InitializeResult:
     server._skip_jdtls = False
     server._skip_jdtls_registration = False
     server._init_generation += 1
+    server._session_opened_uris.clear()
     _jdtls_capabilities_registered = False
 
     jdtls_override = os.environ.get("JAVA_FUNCTIONAL_LSP_JDTLS", "").strip().lower()
@@ -578,6 +670,9 @@ async def on_did_open(params: lsp.DidOpenTextDocumentParams) -> None:
     didOpen response isn't delayed by jdtls cold-start.
     """
     uri = params.text_document.uri
+    # Must precede any await: same-loop jdtls diagnostic callbacks need to
+    # observe this URI before they arrive to avoid the publish getting gated.
+    server._record_opened(uri)
 
     if server._skip_jdtls:
         # Skip all jdtls forwarding — custom diagnostics only.

{java_functional_lsp-0.9.12 → java_functional_lsp-0.9.14}/tests/test_e2e_jdtls.py

@@ -68,6 +68,10 @@ pytestmark = [
 # so a hung jdtls doesn't wedge the suite.
 _E2E_TEST_TIMEOUT_SEC = 120
 _JDTLS_PARSE_WAIT_SEC = 2.5
+# Max wall-clock seconds to poll for a non-empty documentSymbol result.
+# macOS CI runners are slower than Linux; 60s accommodates cold-start variance.
+_JDTLS_SYMBOL_POLL_TIMEOUT_SEC = 60
+_JDTLS_SYMBOL_POLL_INTERVAL_SEC = 1.0
 
 _HELLO_JAVA = """\
 public class Hello {
@@ -260,7 +264,16 @@ class TestJdtlsEndToEnd:
             assert "textDocument" in serialized, f"_serialize_params emitted wrong field names: {serialized.keys()}"
             assert "text_document" not in serialized
 
-            result = await proxy.send_request("textDocument/documentSymbol", serialized)
+            # Poll until jdtls returns a non-empty symbol list or we time out.
+            # A fixed sleep is unreliable on macOS CI where jdtls cold-start
+            # can reach 20s; polling adapts to the actual indexing speed.
+            deadline = asyncio.get_event_loop().time() + _JDTLS_SYMBOL_POLL_TIMEOUT_SEC
+            result = None
+            while asyncio.get_event_loop().time() < deadline:
+                result = await proxy.send_request("textDocument/documentSymbol", serialized)
+                if result:
+                    break
+                await asyncio.sleep(_JDTLS_SYMBOL_POLL_INTERVAL_SEC)
 
         # Primary assertion: jdtls returned something. With a correctly-shaped
         # request, jdtls always returns a list (possibly empty) for a parsable
@@ -274,7 +287,8 @@ class TestJdtlsEndToEnd:
         assert isinstance(result, list)
         # Hello.java declares a top-level class, so we expect at least one symbol.
         assert len(result) > 0, (
-            "jdtls returned an empty symbol list for a file with a top-level class. "
+            "jdtls returned an empty symbol list for a file with a top-level class "
+            f"after polling for {_JDTLS_SYMBOL_POLL_TIMEOUT_SEC}s. "
             "Either jdtls didn't finish parsing or the file wasn't opened correctly."
         )
 

{java_functional_lsp-0.9.12 → java_functional_lsp-0.9.14}/tests/test_proxy.py

@@ -4,7 +4,10 @@ from __future__ import annotations
 
 import asyncio
 import json
+import os
+import shutil
 import subprocess
+import time
 from pathlib import Path
 from typing import Any
 from unittest.mock import MagicMock, patch
@@ -1517,3 +1520,235 @@ class TestWipeDataDir:
         from java_functional_lsp.proxy import _wipe_data_dir
 
         _wipe_data_dir(tmp_path / "ghost")  # should not raise
+
+
+class TestEvictLruWorkspaces:
+    """Tests for _evict_lru_workspaces — count-based LRU eviction of jdtls workspace dirs."""
+
+    @staticmethod
+    def _make_workspace(cache_root: Path, name: str, mtime_age_days: float) -> Path:
+        """Create a fake workspace dir and backdate its mtime."""
+        d = cache_root / name
+        d.mkdir()
+        ts = time.time() - mtime_age_days * 86400.0
+        os.utime(d, (ts, ts))
+        return d
+
+    def test_noop_on_missing_cache_root(self, tmp_path: Path) -> None:
+        """No error when cache_root does not exist."""
+        from java_functional_lsp.proxy import _evict_lru_workspaces
+
+        _evict_lru_workspaces(tmp_path / "nonexistent", max_size=10)
+        # No exception raised — that is the assertion
+
+    def test_noop_when_at_or_below_max_size(self, tmp_path: Path) -> None:
+        """No eviction when count <= max_size."""
+        from java_functional_lsp.proxy import _evict_lru_workspaces
+
+        d1 = self._make_workspace(tmp_path, "aabbccdd1234", mtime_age_days=5)
+        d2 = self._make_workspace(tmp_path, "1122334455ab", mtime_age_days=3)
+        _evict_lru_workspaces(tmp_path, max_size=2)
+        assert d1.exists()
+        assert d2.exists()
+
+    def test_evicts_oldest_when_over_max_size(self, tmp_path: Path) -> None:
+        """Oldest dirs (lowest mtime) are removed; newest are kept."""
+        from java_functional_lsp.proxy import _evict_lru_workspaces
+
+        oldest = self._make_workspace(tmp_path, "aabbccdd1111", mtime_age_days=10)
+        middle = self._make_workspace(tmp_path, "aabbccdd2222", mtime_age_days=5)
+        newest = self._make_workspace(tmp_path, "aabbccdd3333", mtime_age_days=1)
+        _evict_lru_workspaces(tmp_path, max_size=2)
+        assert not oldest.exists()
+        assert middle.exists()
+        assert newest.exists()
+
+    def test_dotfiles_never_evicted(self, tmp_path: Path) -> None:
+        """.version and other dotfiles are excluded from eviction."""
+        from java_functional_lsp.proxy import _evict_lru_workspaces
+
+        marker = tmp_path / ".version"
+        marker.write_text("abc|21")
+        old_ts = time.time() - 999 * 86400.0
+        os.utime(marker, (old_ts, old_ts))
+        # max_size=0 would evict everything — dotfiles must still survive
+        _evict_lru_workspaces(tmp_path, max_size=0)
+        assert marker.exists()
+
+    def test_dotdirs_never_evicted(self, tmp_path: Path) -> None:
+        """Dotfile directories (e.g. .hidden/) are excluded from eviction."""
+        from java_functional_lsp.proxy import _evict_lru_workspaces
+
+        hidden_dir = tmp_path / ".hidden"
+        hidden_dir.mkdir()
+        old_ts = time.time() - 999 * 86400.0
+        os.utime(hidden_dir, (old_ts, old_ts))
+        _evict_lru_workspaces(tmp_path, max_size=0)
+        assert hidden_dir.exists()
+
+    def test_non_directory_entries_ignored(self, tmp_path: Path) -> None:
+        """Plain files in cache_root are never removed."""
+        from java_functional_lsp.proxy import _evict_lru_workspaces
+
+        stray = tmp_path / "stray.txt"
+        stray.write_text("irrelevant")
+        old_ts = time.time() - 999 * 86400.0
+        os.utime(stray, (old_ts, old_ts))
+        _evict_lru_workspaces(tmp_path, max_size=0)
+        assert stray.exists()
+
+    def test_symlinks_never_evicted(self, tmp_path: Path) -> None:
+        """Symlinks in cache_root are excluded — shutil.rmtree must not follow them."""
+        from java_functional_lsp.proxy import _evict_lru_workspaces
+
+        # Target is a dotdir (excluded from candidates) so it is never evicted.
+        # This prevents the symlink from going dangling during the test.
+        target = tmp_path / ".hidden_target"
+        target.mkdir()
+        link = tmp_path / "aabbccdd1111"
+        link.symlink_to(target)
+        old_ts = time.time() - 999 * 86400.0
+        os.utime(link, (old_ts, old_ts))
+        _evict_lru_workspaces(tmp_path, max_size=0)
+        assert link.exists()  # symlink itself must survive
+        assert target.exists()  # target must not be deleted
+
+    def test_dir_mtime_returns_inf_on_oserror(self, tmp_path: Path) -> None:
+        """_dir_mtime returns float('inf') when stat() fails — non-zero sentinel."""
+        from java_functional_lsp.proxy import _dir_mtime
+
+        assert _dir_mtime(tmp_path / "nonexistent") == float("inf")
+
+    def test_stat_error_conservatively_keeps_dir(self, tmp_path: Path) -> None:
+        """Dir whose _dir_mtime returns inf is sorted as newest — conservatively kept.
+
+        Patching _dir_mtime directly (not Path.stat) avoids interfering with
+        is_dir() which also calls stat() internally.
+        """
+        from java_functional_lsp.proxy import _evict_lru_workspaces
+
+        older = self._make_workspace(tmp_path, "aabbccdd1111", mtime_age_days=10)
+        kept_dir = self._make_workspace(tmp_path, "aabbccdd2222", mtime_age_days=5)
+
+        original_dir_mtime = proxy_mod._dir_mtime
+
+        def patched_dir_mtime(path: Path) -> float:
+            if path.name == kept_dir.name:
+                return float("inf")
+            return original_dir_mtime(path)
+
+        with patch("java_functional_lsp.proxy._dir_mtime", patched_dir_mtime):
+            # kept_dir: _dir_mtime returns inf → sorted as newest → kept
+            # older: mtime=10 days ago → sorted as oldest → evicted
+            _evict_lru_workspaces(tmp_path, max_size=1)
+
+        assert kept_dir.exists()  # conservatively kept (inf mtime)
+        assert not older.exists()  # evicted as the oldest accessible dir
+
+    def test_rmtree_error_logged_and_continued(self, tmp_path: Path) -> None:
+        """OSError on rmtree emits a warning and continues evicting remaining dirs."""
+        from java_functional_lsp.proxy import _evict_lru_workspaces
+
+        d1 = self._make_workspace(tmp_path, "aabbccdd1111", mtime_age_days=10)
+        self._make_workspace(tmp_path, "aabbccdd2222", mtime_age_days=5)
+        d3 = self._make_workspace(tmp_path, "aabbccdd3333", mtime_age_days=1)
+
+        call_count = 0
+        original_rmtree = shutil.rmtree
+
+        def patched_rmtree(path: Any, **kw: Any) -> None:
+            nonlocal call_count
+            call_count += 1
+            if Path(path).name == d1.name:
+                raise OSError("busy")
+            original_rmtree(path, **kw)
+
+        with patch("java_functional_lsp.proxy.shutil.rmtree", side_effect=patched_rmtree):
+            with patch("java_functional_lsp.proxy.logger") as mock_logger:
+                _evict_lru_workspaces(tmp_path, max_size=1)
+                # Warning for d1 (rmtree failed); info for d2 (evicted successfully)
+                assert mock_logger.warning.call_count >= 1
+                assert mock_logger.info.call_count >= 1
+
+        assert d3.exists()  # newest kept
+
+    def test_logs_info_on_eviction(self, tmp_path: Path) -> None:
+        """Info log is emitted for each evicted workspace dir, including 'LRU'."""
+        from java_functional_lsp.proxy import _evict_lru_workspaces
+
+        self._make_workspace(tmp_path, "aabbccdd1111", mtime_age_days=10)
+        self._make_workspace(tmp_path, "aabbccdd2222", mtime_age_days=1)
+
+        with patch("java_functional_lsp.proxy.logger") as mock_logger:
+            _evict_lru_workspaces(tmp_path, max_size=1)
+
+        info_calls = [str(c) for c in mock_logger.info.call_args_list]
+        assert any("aabbccdd1111" in m and "LRU" in m for m in info_calls)
+
+    def test_max_size_param_respected(self, tmp_path: Path) -> None:
+        """Passing max_size=3 keeps exactly 3 dirs (the 3 newest)."""
+        from java_functional_lsp.proxy import _evict_lru_workspaces
+
+        dirs = [self._make_workspace(tmp_path, f"workspace{i:04d}", mtime_age_days=float(10 - i)) for i in range(6)]
+        _evict_lru_workspaces(tmp_path, max_size=3)
+        surviving = [d for d in dirs if d.exists()]
+        assert len(surviving) == 3
+        # The 3 newest (smallest age = largest mtime) must survive
+        for d in dirs[-3:]:
+            assert d.exists()
+
+
+class TestParseMaxWorkspaces:
+    """Tests for _parse_max_workspaces — config validation for the LRU cap."""
+
+    def test_none_config_returns_default(self) -> None:
+        from java_functional_lsp.proxy import _WORKSPACE_CACHE_MAX_SIZE, _parse_max_workspaces
+
+        assert _parse_max_workspaces(None) == _WORKSPACE_CACHE_MAX_SIZE
+
+    def test_empty_config_returns_default(self) -> None:
+        from java_functional_lsp.proxy import _WORKSPACE_CACHE_MAX_SIZE, _parse_max_workspaces
+
+        assert _parse_max_workspaces({}) == _WORKSPACE_CACHE_MAX_SIZE
+
+    def test_missing_cache_key_returns_default(self) -> None:
+        from java_functional_lsp.proxy import _WORKSPACE_CACHE_MAX_SIZE, _parse_max_workspaces
+
+        assert _parse_max_workspaces({"jdtls": {}}) == _WORKSPACE_CACHE_MAX_SIZE
+
+    def test_valid_value_is_returned(self) -> None:
+        from java_functional_lsp.proxy import _parse_max_workspaces
+
+        assert _parse_max_workspaces({"cache": {"maxWorkspaces": 5}}) == 5
+        assert _parse_max_workspaces({"cache": {"maxWorkspaces": 1}}) == 1
+        assert _parse_max_workspaces({"cache": {"maxWorkspaces": 100}}) == 100
+
+    def test_string_integer_is_accepted(self) -> None:
+        """A string that represents a valid integer (e.g. from JSON) is parsed."""
+        from java_functional_lsp.proxy import _parse_max_workspaces
+
+        assert _parse_max_workspaces({"cache": {"maxWorkspaces": "7"}}) == 7
+
+    def test_invalid_string_returns_default_with_warning(self) -> None:
+        from java_functional_lsp.proxy import _WORKSPACE_CACHE_MAX_SIZE, _parse_max_workspaces
+
+        with patch("java_functional_lsp.proxy.logger") as mock_logger:
+            result = _parse_max_workspaces({"cache": {"maxWorkspaces": "bad"}})
+        assert result == _WORKSPACE_CACHE_MAX_SIZE
+        mock_logger.warning.assert_called_once()
+
+    def test_zero_returns_default_with_warning(self) -> None:
+        from java_functional_lsp.proxy import _WORKSPACE_CACHE_MAX_SIZE, _parse_max_workspaces
+
+        with patch("java_functional_lsp.proxy.logger") as mock_logger:
+            result = _parse_max_workspaces({"cache": {"maxWorkspaces": 0}})
+        assert result == _WORKSPACE_CACHE_MAX_SIZE
+        mock_logger.warning.assert_called_once()
+
+    def test_negative_returns_default_with_warning(self) -> None:
+        from java_functional_lsp.proxy import _WORKSPACE_CACHE_MAX_SIZE, _parse_max_workspaces
+
+        with patch("java_functional_lsp.proxy.logger") as mock_logger:
+            result = _parse_max_workspaces({"cache": {"maxWorkspaces": -1}})
+        assert result == _WORKSPACE_CACHE_MAX_SIZE
+        mock_logger.warning.assert_called_once()