java-functional-lsp 0.7.2__tar.gz → 0.7.4__tar.gz

{java_functional_lsp-0.7.2 → java_functional_lsp-0.7.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: java-functional-lsp
-Version: 0.7.2
+Version: 0.7.4
 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
@@ -33,7 +33,7 @@ Description-Content-Type: text/markdown
 [![Python](https://img.shields.io/pypi/pyversions/java-functional-lsp?v=1)](https://pypi.org/project/java-functional-lsp/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-A Java Language Server that provides two things in one:
+A Java Language Server that provides three things in one:
 
 1. **Full Java language support** — completions, hover, go-to-definition, compile errors, missing imports — by proxying [Eclipse jdtls](https://github.com/eclipse-jdtls/eclipse.jdt.ls) under the hood
 2. **16 functional programming rules** — catches anti-patterns and suggests Vavr/Lombok/Spring alternatives, all before compilation

{java_functional_lsp-0.7.2 → java_functional_lsp-0.7.4}/README.md

@@ -5,7 +5,7 @@
 [![Python](https://img.shields.io/pypi/pyversions/java-functional-lsp?v=1)](https://pypi.org/project/java-functional-lsp/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-A Java Language Server that provides two things in one:
+A Java Language Server that provides three things in one:
 
 1. **Full Java language support** — completions, hover, go-to-definition, compile errors, missing imports — by proxying [Eclipse jdtls](https://github.com/eclipse-jdtls/eclipse.jdt.ls) under the hood
 2. **16 functional programming rules** — catches anti-patterns and suggests Vavr/Lombok/Spring alternatives, all before compilation

{java_functional_lsp-0.7.2 → java_functional_lsp-0.7.4}/pyproject.toml

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

{java_functional_lsp-0.7.2 → java_functional_lsp-0.7.4}/src/java_functional_lsp/__init__.py

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

{java_functional_lsp-0.7.2 → java_functional_lsp-0.7.4}/src/java_functional_lsp/proxy.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import asyncio
+import copy
 import hashlib
 import json
 import logging
@@ -12,6 +13,7 @@ import re
 import shutil
 import subprocess
 from collections.abc import Callable, Mapping
+from functools import lru_cache
 from pathlib import Path
 from typing import Any
 
@@ -311,6 +313,47 @@ async def read_message(reader: asyncio.StreamReader) -> dict[str, Any] | None:
         return None
 
 
+_BUILD_FILES = ("pom.xml", "build.gradle", "build.gradle.kts")
+_WORKSPACE_DID_CHANGE_FOLDERS = "workspace/didChangeWorkspaceFolders"
+_MAX_QUEUED_NOTIFICATIONS = 200
+
+
+@lru_cache(maxsize=256)
+def _cached_module_root(dir_path: str) -> str | None:
+    """Cached walk up from *dir_path* to find nearest directory with a build file."""
+    current = Path(dir_path)
+    while True:
+        if any((current / bf).is_file() for bf in _BUILD_FILES):
+            return str(current)
+        parent = current.parent
+        if parent == current:
+            return None
+        current = parent
+
+
+def find_module_root(file_path: str) -> str | None:
+    """Walk up from *file_path* to find the nearest directory containing a build file.
+
+    Returns the directory path, or ``None`` if no build file is found before
+    reaching the filesystem root. Results are cached by parent directory.
+    """
+    return _cached_module_root(str(Path(file_path).parent))
+
+
+def _resolve_module_uri(file_uri: str) -> str | None:
+    """Convert a file URI to the URI of its nearest module root, or None."""
+    from pygls.uris import from_fs_path, to_fs_path
+
+    file_path = to_fs_path(file_uri)
+    if not file_path:
+        return None
+    module_root = find_module_root(file_path)
+    if module_root is None:
+        return None
+    module_uri = from_fs_path(module_root)
+    return module_uri or None
+
+
 class JdtlsProxy:
     """Manages a jdtls subprocess and provides async request/notification forwarding."""
 
@@ -324,6 +367,17 @@ class JdtlsProxy:
         self._on_diagnostics = on_diagnostics
         self._available = False
         self._jdtls_capabilities: dict[str, Any] = {}
+        # Lazy-start state
+        self._start_lock = asyncio.Lock()
+        self._starting = False
+        self._start_failed = False
+        self._jdtls_on_path = False
+        self._lazy_start_fired = False
+        self._queued_notifications: list[tuple[str, Any]] = []
+        self._original_root_uri: str | None = None
+        self._initial_module_uri: str | None = None
+        self._added_module_uris: set[str] = set()
+        self._workspace_expanded = False
 
     @property
     def is_available(self) -> bool:
@@ -339,31 +393,55 @@ class JdtlsProxy:
         """Get the latest jdtls diagnostics for a URI."""
         return list(self._diagnostics_cache.get(uri, []))
 
-    async def start(self, init_params: dict[str, Any]) -> bool:
-        """Start jdtls subprocess and initialize it."""
+    def check_available(self) -> bool:
+        """Check if jdtls is on PATH (lightweight, no subprocess started)."""
+        self._jdtls_on_path = shutil.which("jdtls") is not None
+        if not self._jdtls_on_path:
+            logger.warning("jdtls not found on PATH — running in standalone mode (custom rules only)")
+        return self._jdtls_on_path
+
+    async def start(self, init_params: dict[str, Any], *, module_root_uri: str | None = None) -> bool:
+        """Start jdtls subprocess and initialize it.
+
+        If *module_root_uri* is provided, jdtls is scoped to that module for
+        fast startup. The data-directory hash is always based on the original
+        workspace root (from init_params) so the index persists across restarts.
+        """
         jdtls_path = shutil.which("jdtls")
         if not jdtls_path:
-            logger.warning("jdtls not found on PATH — running in standalone mode (custom rules only)")
             return False
 
-        # jdtls requires a -data directory for workspace metadata (index, classpath, build state).
-        # Use ~/.cache/jdtls-data/<hash> so it persists across reboots and LSP restarts.
-        # Fallback order mirrors LSP spec: rootUri → rootPath → cwd.
-        root_uri = init_params.get("rootUri") or init_params.get("rootPath") or str(Path.cwd())
-        workspace_hash = hashlib.sha256(root_uri.encode()).hexdigest()[:12]
+        # Data-dir hash based on original workspace root (stable across module changes).
+        original_root: str = init_params.get("rootUri") or init_params.get("rootPath") or str(Path.cwd())
+        self._original_root_uri = original_root
+        workspace_hash = hashlib.sha256(original_root.encode()).hexdigest()[:12]
         data_dir = Path.home() / ".cache" / "jdtls-data" / workspace_hash
         data_dir.mkdir(parents=True, exist_ok=True)
 
-        # Build a clean environment for jdtls: detect Java 21+ and set JAVA_HOME
-        # explicitly, or strip JAVA_HOME if the inherited value points at an older
-        # Java (e.g. an IDE launched us with a project SDK of Java 8). Without this,
-        # jdtls 1.57+ fails with "jdtls requires at least Java 21" during its
-        # Python launcher's version check.
-        #
-        # build_jdtls_env() issues several blocking subprocess calls (java -version,
-        # /usr/libexec/java_home) to detect a suitable JDK. Run it in a thread pool
-        # so those calls don't block the asyncio event loop — the IDE's LSP handshake
-        # messages would otherwise stall for up to a few seconds during startup.
+        # Deep copy to avoid mutating server._init_params.
+        effective_params = copy.deepcopy(init_params)
+        effective_root_uri = module_root_uri or original_root
+        if module_root_uri:
+            effective_params["rootUri"] = module_root_uri
+            from pygls.uris import to_fs_path
+
+            effective_params["rootPath"] = to_fs_path(module_root_uri)
+            logger.info(
+                "jdtls: scoping to module %s (full root: %s)",
+                _redact_path(module_root_uri),
+                _redact_path(original_root),
+            )
+
+        # Inject workspaceFolders capability for later expansion.
+        caps = effective_params.setdefault("capabilities", {})
+        ws = caps.setdefault("workspace", {})
+        ws["workspaceFolders"] = True
+
+        # Track the initial module as already loaded.
+        self._initial_module_uri = module_root_uri
+        self._added_module_uris.add(effective_root_uri)
+
+        # Build a clean environment for jdtls.
         loop = asyncio.get_running_loop()
         jdtls_env = await loop.run_in_executor(None, build_jdtls_env)
 
@@ -385,14 +463,12 @@ class JdtlsProxy:
                 _redact_path(jdtls_env.get("JAVA_HOME")),
             )
 
-            # Start background readers for stdout (JSON-RPC) and stderr (diagnostics/errors)
             assert self._process.stdout is not None
             self._reader_task = asyncio.create_task(self._reader_loop(self._process.stdout))
             if self._process.stderr is not None:
                 self._stderr_task = asyncio.create_task(self._stderr_reader(self._process.stderr))
 
-            # Send initialize request
-            result = await self.send_request("initialize", init_params)
+            result = await self.send_request("initialize", effective_params)
             if result is None:
                 logger.error("jdtls initialize request failed or timed out")
                 await self.stop()
@@ -401,7 +477,6 @@ class JdtlsProxy:
             self._jdtls_capabilities = result.get("capabilities", {})
             logger.info("jdtls initialized (capabilities: %s)", list(self._jdtls_capabilities.keys()))
 
-            # Send initialized notification
             await self.send_notification("initialized", {})
             self._available = True
             return True
@@ -410,6 +485,95 @@ class JdtlsProxy:
             logger.error("Failed to start jdtls: %s", e)
             return False
 
+    async def ensure_started(self, init_params: dict[str, Any], file_uri: str) -> bool:
+        """Start jdtls lazily, scoped to the module containing *file_uri*.
+
+        Thread-safe: uses asyncio.Lock to prevent double-start from rapid
+        didOpen calls. Sets ``_start_failed`` on failure to prevent retries.
+        """
+        if self._available:
+            return True
+        if self._start_failed or not self._jdtls_on_path:
+            return False
+
+        async with self._start_lock:
+            if self._available:
+                return True
+
+            self._starting = True
+            try:
+                module_uri = _resolve_module_uri(file_uri)
+                started = await self.start(init_params, module_root_uri=module_uri)
+                if not started:
+                    self._start_failed = True
+                    self._queued_notifications.clear()
+                return started
+            finally:
+                self._starting = False
+
+    def queue_notification(self, method: str, params: Any) -> None:
+        """Buffer a notification for replay after jdtls starts.
+
+        Capped at ``_MAX_QUEUED_NOTIFICATIONS`` to prevent unbounded memory
+        growth during long jdtls startup. Oldest entries are dropped on overflow.
+        """
+        if len(self._queued_notifications) >= _MAX_QUEUED_NOTIFICATIONS:
+            self._queued_notifications.pop(0)
+        self._queued_notifications.append((method, params))
+
+    async def flush_queued_notifications(self) -> None:
+        """Send all queued notifications to jdtls."""
+        queue, self._queued_notifications = self._queued_notifications, []
+        for method, params in queue:
+            await self.send_notification(method, params)
+
+    async def add_module_if_new(self, file_uri: str) -> None:
+        """Add the module containing *file_uri* to jdtls if not already added."""
+        if not self._available:
+            return
+        module_uri = _resolve_module_uri(file_uri)
+        if module_uri is None or module_uri in self._added_module_uris:
+            return
+        self._added_module_uris.add(module_uri)
+        from pygls.uris import to_fs_path
+
+        logger.info("jdtls: adding module %s", _redact_path(to_fs_path(module_uri)))
+        mod_name = Path(to_fs_path(module_uri) or module_uri).name
+        await self.send_notification(
+            _WORKSPACE_DID_CHANGE_FOLDERS,
+            {"event": {"added": [{"uri": module_uri, "name": mod_name}], "removed": []}},
+        )
+
+    async def expand_full_workspace(self) -> None:
+        """Expand jdtls workspace to the full monorepo root (background task).
+
+        Removes the initial module-scoped folder and adds the full root to
+        avoid double-indexing.
+        """
+        if self._workspace_expanded or not self._available or not self._original_root_uri:
+            return
+        from pygls.uris import from_fs_path, to_fs_path
+
+        root_path = to_fs_path(self._original_root_uri) or self._original_root_uri
+        root_uri = from_fs_path(root_path) or self._original_root_uri
+        if root_uri in self._added_module_uris:
+            self._workspace_expanded = True
+            return
+        self._added_module_uris.add(root_uri)
+
+        # Remove initial module folder to avoid double-indexing.
+        removed: list[dict[str, str]] = []
+        if self._initial_module_uri and self._initial_module_uri != root_uri:
+            ini_path = to_fs_path(self._initial_module_uri) or self._initial_module_uri
+            removed.append({"uri": self._initial_module_uri, "name": Path(ini_path).name})
+
+        logger.info("jdtls: expanding to full workspace %s", _redact_path(root_path))
+        await self.send_notification(
+            _WORKSPACE_DID_CHANGE_FOLDERS,
+            {"event": {"added": [{"uri": root_uri, "name": Path(root_path).name}], "removed": removed}},
+        )
+        self._workspace_expanded = True
+
     async def stop(self) -> None:
         """Shutdown jdtls subprocess gracefully."""
         self._available = False

{java_functional_lsp-0.7.2 → java_functional_lsp-0.7.4}/src/java_functional_lsp/server.py

@@ -77,6 +77,8 @@ server = JavaFunctionalLspServer()
 
 # Debounce state for didChange events (only affects human typing in IDEs, not agents)
 _pending: dict[str, asyncio.Task[None]] = {}
+# Background tasks (prevent GC of fire-and-forget tasks)
+_bg_tasks: set[asyncio.Task[None]] = set()
 _DEBOUNCE_SECONDS = 0.15
 
 
@@ -228,11 +230,11 @@ def on_initialize(params: lsp.InitializeParams) -> lsp.InitializeResult:
                 change=lsp.TextDocumentSyncKind.Full,
                 save=lsp.SaveOptions(include_text=True),
             ),
-            completion_provider=lsp.CompletionOptions(trigger_characters=["."]),
-            hover_provider=True,
-            definition_provider=True,
-            references_provider=True,
-            document_symbol_provider=True,
+            # Only advertise capabilities we own (custom diagnostics + code actions).
+            # jdtls-dependent features (hover, definition, references, completion,
+            # documentSymbol) are registered dynamically after jdtls starts — see
+            # on_initialized(). This prevents us from claiming hover when jdtls
+            # isn't ready, which would suppress the IDE's diagnostic tooltips.
             code_action_provider=lsp.CodeActionOptions(
                 code_action_kinds=[lsp.CodeActionKind.QuickFix],
             ),
@@ -242,16 +244,75 @@ def on_initialize(params: lsp.InitializeParams) -> lsp.InitializeResult:
 
 @server.feature(lsp.INITIALIZED)
 async def on_initialized(params: lsp.InitializedParams) -> None:
-    """Start jdtls proxy after initialization."""
+    """Check jdtls availability; actual start deferred to first didOpen."""
     logger.info(
         "java-functional-lsp initialized (rules: %s)",
         list(server._config.get("rules", {}).keys()) or "all defaults",
     )
-    started = await server._proxy.start(server._init_params)
-    if started:
-        logger.info("jdtls proxy active — full Java language support enabled")
+    if server._proxy.check_available():
+        logger.info("jdtls found on PATH — will start lazily on first file open")
     else:
-        logger.info("jdtls proxy unavailable — running with custom rules only")
+        logger.info("jdtls not on PATH — running with custom rules only")
+
+
+_JAVA_SELECTOR = [lsp.TextDocumentFilterLanguage(language="java")]
+
+_JDTLS_REG_PREFIX = "jdtls-"
+
+# jdtls-dependent capabilities registered dynamically after the proxy starts.
+# Each entry: (id_suffix, LSP method, registration options class, extra kwargs).
+_JDTLS_CAPABILITIES: list[tuple[str, str, type[Any], dict[str, Any]]] = [
+    ("completion", lsp.TEXT_DOCUMENT_COMPLETION, lsp.CompletionRegistrationOptions, {"trigger_characters": ["."]}),
+    ("hover", lsp.TEXT_DOCUMENT_HOVER, lsp.HoverRegistrationOptions, {}),
+    ("definition", lsp.TEXT_DOCUMENT_DEFINITION, lsp.DefinitionRegistrationOptions, {}),
+    ("references", lsp.TEXT_DOCUMENT_REFERENCES, lsp.ReferenceRegistrationOptions, {}),
+    ("document-symbol", lsp.TEXT_DOCUMENT_DOCUMENT_SYMBOL, lsp.DocumentSymbolRegistrationOptions, {}),
+]
+
+# Maps LSP method → handler function for dynamic registration.
+_JDTLS_HANDLERS: dict[str, Any] = {}
+
+# Set after first successful registration to prevent FeatureAlreadyRegisteredError.
+_jdtls_capabilities_registered = False
+
+
+def _build_jdtls_registrations() -> list[lsp.Registration]:
+    """Build LSP Registration objects for jdtls-dependent capabilities."""
+    return [
+        lsp.Registration(
+            id=f"{_JDTLS_REG_PREFIX}{suffix}",
+            method=method,
+            register_options=_converter.unstructure(opts_cls(document_selector=_JAVA_SELECTOR, **extra)),
+        )
+        for suffix, method, opts_cls, extra in _JDTLS_CAPABILITIES
+    ]
+
+
+async def _register_jdtls_capabilities() -> None:
+    """Dynamically register jdtls-dependent capabilities after the proxy starts.
+
+    We don't advertise these in the static InitializeResult because doing so
+    would make the IDE defer hover/definition/etc to us even before jdtls is
+    ready, which suppresses the IDE's built-in diagnostic tooltips.
+
+    Idempotent: safe to call multiple times (e.g., proxy restart).
+    """
+    global _jdtls_capabilities_registered
+    if _jdtls_capabilities_registered:
+        return
+
+    try:
+        # Register handlers so pygls dispatches incoming requests to them.
+        for method, handler in _JDTLS_HANDLERS.items():
+            server.feature(method)(handler)
+
+        # Tell the client we now support these capabilities.
+        registrations = _build_jdtls_registrations()
+        await server.client_register_capability_async(lsp.RegistrationParams(registrations=registrations))
+        _jdtls_capabilities_registered = True
+        logger.info("Dynamically registered jdtls capabilities (hover, definition, references, completion, symbol)")
+    except Exception:
+        logger.warning("Failed to dynamically register jdtls capabilities", exc_info=True)
 
 
 # --- Document sync (forward to jdtls + run custom analyzers) ---
@@ -270,20 +331,50 @@ async def _deferred_validate(uri: str) -> None:
     _analyze_and_publish(uri)
 
 
+def _forward_or_queue(method: str, serialized: Any) -> None:
+    """Forward a notification to jdtls if available, or queue it if starting."""
+    if server._proxy.is_available:
+        task = asyncio.create_task(server._proxy.send_notification(method, serialized))
+        _bg_tasks.add(task)
+        task.add_done_callback(_bg_tasks.discard)
+    elif server._proxy._starting:
+        server._proxy.queue_notification(method, serialized)
+
+
 @server.feature(lsp.TEXT_DOCUMENT_DID_OPEN)
 async def on_did_open(params: lsp.DidOpenTextDocumentParams) -> None:
-    """Forward to jdtls and analyze immediately."""
+    """Forward to jdtls (starting lazily if needed) and analyze immediately.
+
+    Custom diagnostics always publish immediately regardless of jdtls state.
+    jdtls startup is non-blocking — it runs in the background so the first
+    didOpen response isn't delayed by jdtls cold-start.
+    """
+    uri = params.text_document.uri
+    serialized = _serialize_params(params)
+
     if server._proxy.is_available:
-        await server._proxy.send_notification("textDocument/didOpen", _serialize_params(params))
-    _analyze_and_publish(params.text_document.uri)
+        # Fast path: jdtls running. Forward didOpen + add module if new.
+        await server._proxy.send_notification("textDocument/didOpen", serialized)
+        await server._proxy.add_module_if_new(uri)
+    elif server._proxy._jdtls_on_path and not server._proxy._start_failed:
+        # Queue the didOpen (whether this is the first file or a subsequent one during startup).
+        server._proxy.queue_notification("textDocument/didOpen", serialized)
+        if not server._proxy._lazy_start_fired:
+            # First file: kick off lazy start in background.
+            server._proxy._lazy_start_fired = True
+            task = asyncio.create_task(_lazy_start_jdtls(uri))
+            _bg_tasks.add(task)
+            task.add_done_callback(_bg_tasks.discard)
+
+    # Custom diagnostics always publish immediately — never blocked by jdtls.
+    _analyze_and_publish(uri)
 
 
 @server.feature(lsp.TEXT_DOCUMENT_DID_CHANGE)
 async def on_did_change(params: lsp.DidChangeTextDocumentParams) -> None:
     """Forward to jdtls and schedule debounced re-analysis."""
     uri = params.text_document.uri
-    if server._proxy.is_available:
-        await server._proxy.send_notification("textDocument/didChange", _serialize_params(params))
+    _forward_or_queue("textDocument/didChange", _serialize_params(params))
     # Cancel pending validation, schedule new one (150ms debounce for IDE typing)
     if uri in _pending:
         _pending[uri].cancel()
@@ -293,8 +384,7 @@ async def on_did_change(params: lsp.DidChangeTextDocumentParams) -> None:
 @server.feature(lsp.TEXT_DOCUMENT_DID_SAVE)
 async def on_did_save(params: lsp.DidSaveTextDocumentParams) -> None:
     """Forward to jdtls and re-analyze immediately (no debounce on save)."""
-    if server._proxy.is_available:
-        await server._proxy.send_notification("textDocument/didSave", _serialize_params(params))
+    _forward_or_queue("textDocument/didSave", _serialize_params(params))
     _analyze_and_publish(params.text_document.uri)
 
 
@@ -307,15 +397,50 @@ async def on_did_close(params: lsp.DidCloseTextDocumentParams) -> None:
         del _pending[uri]
     # Clear diagnostics for the closed document (LSP best practice)
     server.text_document_publish_diagnostics(lsp.PublishDiagnosticsParams(uri=uri, diagnostics=[]))
-    if server._proxy.is_available:
-        await server._proxy.send_notification("textDocument/didClose", _serialize_params(params))
+    _forward_or_queue("textDocument/didClose", _serialize_params(params))
+
+
+async def _lazy_start_jdtls(file_uri: str) -> None:
+    """Background task: start jdtls scoped to the module containing *file_uri*.
+
+    Runs in the background so ``on_did_open`` returns immediately with custom
+    diagnostics. After jdtls initializes, registers capabilities, flushes
+    queued notifications, and schedules workspace expansion.
+    """
+    try:
+        started = await server._proxy.ensure_started(server._init_params, file_uri)
+        if started:
+            logger.info("jdtls proxy active — full Java language support enabled")
+            await _register_jdtls_capabilities()
+            await server._proxy.flush_queued_notifications()
+            await _expand_workspace_background()
+    except Exception:
+        logger.warning("jdtls lazy start failed", exc_info=True)
+
+
+async def _expand_workspace_background() -> None:
+    """Background task: expand jdtls workspace to full monorepo root.
+
+    Runs after jdtls finishes initializing with the first module scope.
+    The user's actively-opened modules are loaded immediately via
+    ``add_module_if_new()`` in ``on_did_open``; this adds the full root
+    so cross-module references for unopened files also work.
+    """
+    try:
+        await server._proxy.expand_full_workspace()
+    except Exception:
+        logger.warning("Failed to expand jdtls workspace", exc_info=True)
 
 
-# --- Forwarded features (jdtls passthrough) ---
+# --- jdtls passthrough handlers (registered dynamically, NOT at module level) ---
+#
+# These are NOT decorated with @server.feature because pygls auto-advertises
+# capabilities for decorated handlers. Instead, they are collected in
+# _JDTLS_HANDLERS and registered inside _register_jdtls_capabilities() so
+# they only activate after jdtls starts.
 
 
-@server.feature(lsp.TEXT_DOCUMENT_COMPLETION)
-async def on_completion(params: lsp.CompletionParams) -> lsp.CompletionList | None:
+async def _on_completion(params: lsp.CompletionParams) -> lsp.CompletionList | None:
     """Forward completion request to jdtls."""
     if not server._proxy.is_available:
         return None
@@ -328,8 +453,7 @@ async def on_completion(params: lsp.CompletionParams) -> lsp.CompletionList | No
         return None
 
 
-@server.feature(lsp.TEXT_DOCUMENT_HOVER)
-async def on_hover(params: lsp.HoverParams) -> lsp.Hover | None:
+async def _on_hover(params: lsp.HoverParams) -> lsp.Hover | None:
     """Forward hover request to jdtls."""
     if not server._proxy.is_available:
         return None
@@ -342,8 +466,7 @@ async def on_hover(params: lsp.HoverParams) -> lsp.Hover | None:
         return None
 
 
-@server.feature(lsp.TEXT_DOCUMENT_DEFINITION)
-async def on_definition(params: lsp.DefinitionParams) -> list[lsp.Location] | None:
+async def _on_definition(params: lsp.DefinitionParams) -> list[lsp.Location] | None:
     """Forward go-to-definition request to jdtls."""
     if not server._proxy.is_available:
         return None
@@ -358,8 +481,7 @@ async def on_definition(params: lsp.DefinitionParams) -> list[lsp.Location] | No
         return None
 
 
-@server.feature(lsp.TEXT_DOCUMENT_REFERENCES)
-async def on_references(params: lsp.ReferenceParams) -> list[lsp.Location] | None:
+async def _on_references(params: lsp.ReferenceParams) -> list[lsp.Location] | None:
     """Forward find-references request to jdtls."""
     if not server._proxy.is_available:
         return None
@@ -372,8 +494,7 @@ async def on_references(params: lsp.ReferenceParams) -> list[lsp.Location] | Non
         return None
 
 
-@server.feature(lsp.TEXT_DOCUMENT_DOCUMENT_SYMBOL)
-async def on_document_symbol(params: lsp.DocumentSymbolParams) -> list[lsp.DocumentSymbol] | None:
+async def _on_document_symbol(params: lsp.DocumentSymbolParams) -> list[lsp.DocumentSymbol] | None:
     """Forward document symbol request to jdtls."""
     if not server._proxy.is_available:
         return None
@@ -386,6 +507,18 @@ async def on_document_symbol(params: lsp.DocumentSymbolParams) -> list[lsp.Docum
         return None
 
 
+# Populate handler map for dynamic registration.
+_JDTLS_HANDLERS.update(
+    {
+        lsp.TEXT_DOCUMENT_COMPLETION: _on_completion,
+        lsp.TEXT_DOCUMENT_HOVER: _on_hover,
+        lsp.TEXT_DOCUMENT_DEFINITION: _on_definition,
+        lsp.TEXT_DOCUMENT_REFERENCES: _on_references,
+        lsp.TEXT_DOCUMENT_DOCUMENT_SYMBOL: _on_document_symbol,
+    }
+)
+
+
 # --- Code actions (quick fixes) ---
 
 # Human-readable titles for code actions