java-functional-lsp 0.8.1__tar.gz → 0.9.1__tar.gz

{java_functional_lsp-0.8.1 → java_functional_lsp-0.9.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: java-functional-lsp
-Version: 0.8.1
+Version: 0.9.1
 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.8.1 → java_functional_lsp-0.9.1}/pyproject.toml

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

{java_functional_lsp-0.8.1 → java_functional_lsp-0.9.1}/src/java_functional_lsp/__init__.py

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

java_functional_lsp-0.9.1/src/java_functional_lsp/merkle.py

@@ -0,0 +1,222 @@
+"""Module snapshot tracking for incremental file-change detection between sessions.
+
+Each Java module's source files are hashed into a ``ModuleSnapshot``.
+On the next plugin session the stored snapshot is compared against the
+current one; only files that actually changed are forwarded to jdtls via
+``workspace/didChangeWatchedFiles``, letting it do an incremental rebuild
+instead of a full cold-start re-index.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import hashlib
+import json
+import logging
+import os
+import tempfile
+from collections.abc import Iterator
+from dataclasses import dataclass
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+# Files and directories tracked / skipped during snapshot.
+_BUILD_FILES: frozenset[str] = frozenset({"pom.xml", "build.gradle", "build.gradle.kts"})
+_SKIP_DIRS: frozenset[str] = frozenset({"target", ".git", "node_modules", ".gradle", "build", ".idea", ".mvn"})
+
+# Safety bound: modules larger than this are skipped to prevent multi-second
+# executor stalls (e.g., when jdtls is scoped to the monorepo root).
+_MAX_FILES = 20_000
+
+# Upper bound on entries in a persisted snapshot (sanity / DoS guard).
+_MAX_SNAPSHOT_FILES = 100_000
+
+_READ_CHUNK = 65536  # 64 KiB per read — bounds per-file memory usage during hashing
+
+
+def _blake2b_file(path: Path) -> str:
+    """Return a 64-char BLAKE2b hex digest of *path*, reading in 64 KiB chunks.
+
+    Streams the file instead of loading it entirely into memory, bounding
+    per-file heap usage to ``_READ_CHUNK`` bytes regardless of file size.
+    """
+    h = hashlib.blake2b(digest_size=32)
+    with path.open("rb") as fh:
+        while chunk := fh.read(_READ_CHUNK):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+@dataclass(frozen=True)
+class TreeDiff:
+    """Set-based diff between two ``ModuleSnapshot`` instances."""
+
+    added: frozenset[str]
+    modified: frozenset[str]
+    removed: frozenset[str]
+
+    @property
+    def is_empty(self) -> bool:
+        return not (self.added or self.modified or self.removed)
+
+    @property
+    def has_build_file_changes(self) -> bool:
+        """True if any build file (pom.xml, build.gradle, …) changed."""
+        return any(Path(p).name in _BUILD_FILES for bucket in (self.added, self.modified, self.removed) for p in bucket)
+
+    @property
+    def all_changed(self) -> frozenset[str]:
+        """Union of added and modified relative paths (files present on disk)."""
+        return self.added | self.modified
+
+
+@dataclass
+class ModuleSnapshot:
+    """Snapshot of a Java module's tracked source files.
+
+    ``root_hash`` is a BLAKE2b hash of all ``(relative_path, content_hash)``
+    pairs sorted by path.  Two snapshots with the same ``root_hash`` are
+    identical; this enables an O(1) equality check before the O(N) per-file
+    diff.
+
+    ``files`` maps each tracked relative path to the BLAKE2b hash of its
+    content at snapshot time.
+    """
+
+    root_hash: str
+    files: dict[str, str]  # relative path → content hash
+
+    # ------------------------------------------------------------------
+    # Construction
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def build(cls, module_root: Path) -> ModuleSnapshot | None:
+        """Scan *module_root* and return a snapshot, or ``None`` if too large.
+
+        Tracked files: ``*.java`` + ``pom.xml`` / ``build.gradle`` /
+        ``build.gradle.kts``.  Directories in ``_SKIP_DIRS`` (``target``,
+        ``.git``, ``node_modules``, …) are pruned from the walk entirely.
+        Symlinks are skipped.  Paths that resolve outside *module_root* are
+        rejected (defense-in-depth against directory traversal).
+        """
+        files: dict[str, str] = {}
+
+        for file_path in _iter_tracked_files(module_root):
+            if len(files) >= _MAX_FILES:
+                logger.warning(
+                    "merkle: module %s has ≥%d tracked files — skipping snapshot",
+                    module_root,
+                    _MAX_FILES,
+                )
+                return None
+            rel = str(file_path.relative_to(module_root))
+            try:
+                files[rel] = _blake2b_file(file_path)
+            except OSError as exc:
+                logger.debug("merkle: could not read %s: %s", file_path, exc)
+
+        # Build root hash incrementally — avoids allocating an O(N) intermediate string.
+        h = hashlib.blake2b(digest_size=32)
+        for p, fh in sorted(files.items()):
+            h.update(f"{p}:{fh}\n".encode())
+        return cls(root_hash=h.hexdigest(), files=files)
+
+    # ------------------------------------------------------------------
+    # Comparison
+    # ------------------------------------------------------------------
+
+    def diff(self, newer: ModuleSnapshot) -> TreeDiff:
+        """Return what changed between *self* (old) and *newer* (current)."""
+        old = self.files
+        new = newer.files
+        added = frozenset(new.keys() - old.keys())
+        removed = frozenset(old.keys() - new.keys())
+        modified = frozenset(p for p in old.keys() & new.keys() if old[p] != new[p])
+        return TreeDiff(added=added, modified=modified, removed=removed)
+
+    # ------------------------------------------------------------------
+    # Persistence
+    # ------------------------------------------------------------------
+
+    def save(self, path: Path) -> None:
+        """Atomically write snapshot to *path* (write to temp then rename).
+
+        The parent directory is created with mode ``0o700`` (owner-only) on
+        first use to prevent other local users from tampering with the cache.
+        """
+        path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+        payload = json.dumps({"root": self.root_hash, "files": self.files}, separators=(",", ":"))
+        fd, tmp = tempfile.mkstemp(dir=path.parent, suffix=".tmp")
+        try:
+            with os.fdopen(fd, "wb") as fh:
+                fh.write(payload.encode())
+            os.replace(tmp, path)
+        except Exception:
+            with contextlib.suppress(OSError):
+                os.unlink(tmp)
+            raise
+
+    @classmethod
+    def load(cls, path: Path) -> ModuleSnapshot | None:
+        """Load a snapshot from *path*.
+
+        Returns ``None`` on missing file, JSON parse error, or invalid
+        content (path traversal attempts, oversized entries, wrong types).
+        Never raises.
+        """
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+            root_hash = data["root"]
+            files = data["files"]
+            if not isinstance(root_hash, str) or not isinstance(files, dict):
+                return None
+            if len(files) > _MAX_SNAPSHOT_FILES:
+                return None
+            # Validate each entry: relative, no traversal, no nulls, str values.
+            valid = all(
+                isinstance(k, str)
+                and isinstance(v, str)
+                and "\x00" not in k
+                and not (p := Path(k)).is_absolute()
+                and ".." not in p.parts
+                for k, v in files.items()
+            )
+            return cls(root_hash=root_hash, files=files) if valid else None
+        except (OSError, KeyError, ValueError):
+            return None
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _iter_tracked_files(module_root: Path) -> Iterator[Path]:
+    """Yield ``.java`` and build files under *module_root*.
+
+    Uses ``os.walk`` with ``followlinks=False`` and prunes ``_SKIP_DIRS``
+    in-place so entire subtrees (``target/``, ``.git/``, …) are never
+    entered.  Symlink files are skipped individually.  Any path that resolves
+    outside *module_root* after symlink expansion is rejected.
+    """
+    module_resolved = module_root.resolve()
+
+    for dirpath_str, dirnames, filenames in os.walk(module_root, followlinks=False):
+        # Prune skip dirs in-place to stop os.walk from descending into them.
+        dirnames[:] = [d for d in dirnames if d not in _SKIP_DIRS]
+
+        dir_path = Path(dirpath_str)
+        for fname in filenames:
+            if not (fname.endswith(".java") or fname in _BUILD_FILES):
+                continue
+            file_path = dir_path / fname
+            if file_path.is_symlink():
+                continue
+            # Reject any path whose resolved form escapes the module root.
+            try:
+                file_path.resolve().relative_to(module_resolved)
+            except ValueError:
+                continue
+            yield file_path

{java_functional_lsp-0.8.1 → java_functional_lsp-0.9.1}/src/java_functional_lsp/proxy.py

@@ -19,6 +19,8 @@ from functools import lru_cache
 from pathlib import Path
 from typing import Any
 
+from .merkle import _BUILD_FILES, ModuleSnapshot, TreeDiff
+
 logger = logging.getLogger(__name__)
 
 REQUEST_TIMEOUT = 30.0  # seconds — per-request timeout for normal operations
@@ -317,7 +319,6 @@ 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
 _MODULE_READY_TIMEOUT = 30.0
@@ -430,7 +431,7 @@ def _resolve_module_uri(file_uri: str) -> str | None:
     if module_root is None:
         return None
     module_uri = from_fs_path(module_root)
-    return module_uri or None
+    return module_uri if module_uri else None
 
 
 def _version_key(name: str) -> tuple[int, ...]:
@@ -444,6 +445,55 @@ def _version_key(name: str) -> tuple[int, ...]:
     return tuple(parts)
 
 
+@lru_cache(maxsize=256)
+def _module_snapshot_path(module_uri: str) -> Path:
+    """Return the path for the persistent snapshot file for *module_uri*.
+
+    Snapshots live under ``~/.cache/jdtls-snapshots/`` — separate from the
+    jdtls data-dir tree so they survive version-bump cache wipes.
+    Each module gets a 12-char BLAKE2b subdirectory (6-byte digest).
+    """
+    h = hashlib.blake2b(module_uri.encode(), digest_size=6).hexdigest()
+    return Path.home() / ".cache" / "jdtls-snapshots" / h / ".snapshot.json"
+
+
+def _compute_module_diff(
+    module_uri: str,
+) -> tuple[TreeDiff | None, ModuleSnapshot] | None:
+    """Blocking: build current snapshot and diff against stored one.
+
+    Returns ``(diff, current_snapshot)`` or ``None`` on error / size limit.
+    ``diff`` is ``None`` when there is no stored snapshot (first session) or
+    the snapshots are identical — the caller should still save the snapshot in
+    both cases.
+
+    Intended to run inside a thread-pool executor.
+    """
+    from pygls.uris import to_fs_path
+
+    module_fs = to_fs_path(module_uri)
+    if not module_fs:
+        return None
+    module_root = Path(module_fs)
+    if not module_root.is_dir():
+        return None
+
+    current = ModuleSnapshot.build(module_root)
+    if current is None:
+        return None  # file count exceeded limit
+
+    snapshot_path = _module_snapshot_path(module_uri)
+    stored = ModuleSnapshot.load(snapshot_path)
+
+    if stored is None:
+        # First session: no diff to compute — caller (_apply_module_diff) will
+        # save the baseline snapshot after the module reaches READY.
+        return (None, current)
+
+    diff = stored.diff(current)
+    return (diff, current)
+
+
 def _clear_cache_on_version_change(cache_root: Path) -> None:
     """Clear jdtls data cache when the server version changes.
 
@@ -534,6 +584,16 @@ class JdtlsProxy:
         self.modules = ModuleRegistry()
         self.has_lombok = False
         self._workspace_expanded = False
+        # Merkle snapshot diff: module_uri → (diff | None, current_snapshot)
+        # Populated by _kick_module_diff (background task on add_module_if_new).
+        # Consumed by server._apply_module_diff after module reaches READY.
+        self._module_diff_results: dict[str, tuple[TreeDiff | None, ModuleSnapshot]] = {}
+        # Task references for in-flight diff computations, keyed by module_uri.
+        # Allows _apply_module_diff to await the task directly if READY fires
+        # before _kick_module_diff stores its result.
+        self._pending_diff_tasks: dict[str, asyncio.Task[None]] = {}
+        # Background tasks created by this proxy (prevents GC of fire-and-forget tasks).
+        self._proxy_bg_tasks: set[asyncio.Task[Any]] = set()
 
     @property
     def is_available(self) -> bool:
@@ -717,6 +777,11 @@ class JdtlsProxy:
         Uses a ``deque(maxlen=200)`` so oldest entries are dropped in O(1)
         when the queue overflows during long jdtls startup.
         """
+        if len(self._queued_notifications) >= _MAX_QUEUED_NOTIFICATIONS:
+            logger.warning(
+                "jdtls: notification queue full (%d cap) — oldest entry dropped; some didOpen events may be missed",
+                _MAX_QUEUED_NOTIFICATIONS,
+            )
         self._queued_notifications.append((method, params))
 
     async def flush_queued_notifications(self) -> None:
@@ -726,6 +791,42 @@ class JdtlsProxy:
         for method, params in queue:
             await self.send_notification(method, params)
 
+    async def _kick_module_diff(self, module_uri: str) -> None:
+        """Background task: compute snapshot diff and stash it for later use.
+
+        Result is stored in ``_module_diff_results`` BEFORE the task is removed
+        from ``_pending_diff_tasks`` to eliminate the TOCTOU window where
+        ``await_module_diff`` could find neither a running task nor a result.
+        """
+        loop = asyncio.get_running_loop()
+        result = await loop.run_in_executor(None, _compute_module_diff, module_uri)
+        # Store result first, then remove from pending — preserves invariant that
+        # once the task is gone from _pending_diff_tasks the result is already readable.
+        if result is not None:
+            self._module_diff_results[module_uri] = result
+        self._pending_diff_tasks.pop(module_uri, None)
+
+    def pop_module_data(self, module_uri: str) -> tuple[TreeDiff | None, ModuleSnapshot] | None:
+        """Pop and return stashed ``(diff, snapshot)`` for *module_uri*, or ``None``."""
+        return self._module_diff_results.pop(module_uri, None)
+
+    async def await_module_diff(self, module_uri: str) -> None:
+        """Wait for the in-flight diff task for *module_uri* to complete, if any.
+
+        Called when the READY signal fires before ``_kick_module_diff`` has
+        stored its result — awaiting the task directly avoids a time-based
+        sleep and ensures the diff is never silently dropped.
+
+        Swallows ``CancelledError`` so that a ``stop()`` call during the wait
+        does not propagate and crash the caller.
+        """
+        task = self._pending_diff_tasks.pop(module_uri, None)
+        if task is not None and not task.done():
+            try:
+                await task
+            except (asyncio.CancelledError, Exception):
+                pass  # result storage is _kick_module_diff's responsibility
+
     async def add_module_if_new(self, file_uri: str) -> str | None:
         """Add the module containing *file_uri* to jdtls if not already added.
 
@@ -736,7 +837,7 @@ class JdtlsProxy:
         Calls ``modules.mark_added()`` before any ``await`` to prevent
         duplicate add calls from concurrent coroutines.
         """
-        if not self._available:
+        if not self._available or self._workspace_expanded:
             return None
         module_uri = _resolve_module_uri(file_uri)
         if module_uri is None or self.modules.was_added(module_uri):
@@ -751,6 +852,13 @@ class JdtlsProxy:
             _WORKSPACE_DID_CHANGE_FOLDERS,
             {"event": {"added": [{"uri": module_uri, "name": mod_name}], "removed": []}},
         )
+        # Fire-and-forget: compute snapshot diff in background so it is ready
+        # when the module reaches READY state.  Does NOT block the jdtls
+        # readiness timeout (which starts ticking at mark_added above).
+        diff_task = asyncio.create_task(self._kick_module_diff(module_uri))
+        self._proxy_bg_tasks.add(diff_task)
+        diff_task.add_done_callback(self._proxy_bg_tasks.discard)
+        self._pending_diff_tasks[module_uri] = diff_task
         return module_uri
 
     async def expand_full_workspace(self) -> None:
@@ -770,11 +878,14 @@ class JdtlsProxy:
             return
         self.modules.mark_added(root_uri)
 
-        # Remove initial module folder to avoid double-indexing.
+        # Remove ALL individually-added modules to prevent double-indexing with
+        # the full root.  This covers both the initial scoped module and any
+        # modules added by add_module_if_new during the ensure_started window.
         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})
+        for uri in list(self.modules._states):
+            if uri != root_uri:
+                p = to_fs_path(uri) or uri
+                removed.append({"uri": uri, "name": Path(p).name})
 
         logger.info("jdtls: expanding to full workspace %s", _redact_path(root_path))
         await self.send_notification(
@@ -792,6 +903,12 @@ class JdtlsProxy:
         if self._stderr_task and not self._stderr_task.done():
             self._stderr_task.cancel()
 
+        for task in list(self._proxy_bg_tasks):
+            task.cancel()
+        self._proxy_bg_tasks.clear()
+        self._module_diff_results.clear()
+        self._pending_diff_tasks.clear()
+
         if self._process and self._process.returncode is None:
             try:
                 await self.send_request("shutdown", None, timeout=5.0)

{java_functional_lsp-0.8.1 → java_functional_lsp-0.9.1}/src/java_functional_lsp/server.py

@@ -12,6 +12,7 @@ import logging
 import os
 import re
 import sys
+from collections.abc import Coroutine
 from pathlib import Path
 from typing import Any
 
@@ -28,7 +29,7 @@ from .analyzers.mutation_checker import MutationChecker
 from .analyzers.null_checker import NullChecker
 from .analyzers.spring_checker import SpringChecker
 from .fixes import get_fix, get_fix_registry_keys
-from .proxy import JdtlsProxy, _resolve_module_uri
+from .proxy import JdtlsProxy, _module_snapshot_path, _resolve_module_uri
 
 logger = logging.getLogger(__name__)
 
@@ -75,20 +76,30 @@ class JavaFunctionalLspServer(LanguageServer):
         self._skip_jdtls_registration: bool = False
         self._init_generation: int = 0
 
-    def _on_jdtls_diagnostics(self, uri: str, diagnostics: list[Any]) -> None:
+    def _on_jdtls_diagnostics(self, uri: str, _diagnostics: list[Any]) -> None:
         """Called when jdtls publishes diagnostics — merge with custom and re-publish.
 
         Also marks the file's module as READY, since receiving diagnostics from
         jdtls is a reliable signal that the module has been indexed (more reliable
         than a first non-None response which may be semantically empty).
+
+        When a module transitions to READY, fires ``_apply_module_diff`` to
+        notify jdtls about any externally changed files (e.g., after git pull).
         """
         if not uri.endswith(".java"):
             return
         module_uri = _resolve_module_uri(uri)
         if module_uri:
+            already_ready = self._proxy.modules.is_ready(module_uri)
             self._proxy.modules.mark_ready(module_uri)
+            if not already_ready:
+                # 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))
         try:
             _analyze_and_publish(uri)
+        except FileNotFoundError:
+            pass  # Virtual jdtls file (e.g., decompiled source in jdtls-data); skip silently.
         except Exception as e:
             logger.error("Error re-publishing diagnostics for %s: %s", uri, e)
 
@@ -102,6 +113,72 @@ _bg_tasks: set[asyncio.Task[None]] = set()
 _DEBOUNCE_SECONDS = 0.15
 
 
+def _fire_and_forget(coro: Coroutine[Any, Any, Any]) -> None:
+    """Schedule *coro* as a background task, preventing GC until it finishes."""
+    task = asyncio.create_task(coro)
+    _bg_tasks.add(task)
+    task.add_done_callback(_bg_tasks.discard)
+
+
+async def _apply_module_diff(proxy: JdtlsProxy, module_uri: str) -> None:
+    """Send ``workspace/didChangeWatchedFiles`` for externally changed files.
+
+    Called (fire-and-forget) when a module reaches READY state.  Pops the
+    ``(diff, snapshot)`` pair computed by ``_kick_module_diff`` during module
+    registration, notifies jdtls about changed files so it can do an
+    incremental rebuild, then persists the updated snapshot to disk.
+
+    No-ops if the diff computation is not yet finished or found no changes.
+    """
+    data = proxy.pop_module_data(module_uri)
+    if data is None:
+        # Race guard: READY may fire before _kick_module_diff finishes.
+        # Await the in-flight task directly (no arbitrary sleep).
+        await proxy.await_module_diff(module_uri)
+        data = proxy.pop_module_data(module_uri)
+    if data is None:
+        return
+    diff, current_snapshot = data
+
+    if diff is not None and not diff.is_empty:
+        from pygls.uris import from_fs_path, to_fs_path
+
+        module_fs = to_fs_path(module_uri) or ""
+        if module_fs:
+            module_path = Path(module_fs)
+            changes = (
+                [
+                    {"uri": u, "type": lsp.FileChangeType.Created}
+                    for rel in diff.added
+                    if (u := from_fs_path(str(module_path / rel)))
+                ]
+                + [
+                    {"uri": u, "type": lsp.FileChangeType.Changed}
+                    for rel in diff.modified
+                    if (u := from_fs_path(str(module_path / rel)))
+                ]
+                + [
+                    {"uri": u, "type": lsp.FileChangeType.Deleted}
+                    for rel in diff.removed
+                    if (u := from_fs_path(str(module_path / rel)))
+                ]
+            )
+            if changes:
+                await proxy.send_notification("workspace/didChangeWatchedFiles", {"changes": changes})
+                logger.info(
+                    "merkle: notified jdtls of %d externally changed file(s) in module",
+                    len(changes),
+                )
+
+    # Always persist the current snapshot so next session has an up-to-date baseline.
+    snapshot_path = _module_snapshot_path(module_uri)
+    loop = asyncio.get_running_loop()
+    try:
+        await loop.run_in_executor(None, current_snapshot.save, snapshot_path)
+    except OSError as exc:
+        logger.warning("merkle: could not save updated snapshot: %s", exc)
+
+
 def _handle_exception(exc_type: type[BaseException], exc_value: BaseException, exc_tb: Any) -> None:
     """Log uncaught exceptions for crash debugging."""
     logger.error("Uncaught exception", exc_info=(exc_type, exc_value, exc_tb))
@@ -342,7 +419,7 @@ def on_initialize(params: lsp.InitializeParams) -> lsp.InitializeResult:
 
 
 @server.feature(lsp.INITIALIZED)
-async def on_initialized(params: lsp.InitializedParams) -> None:
+async def on_initialized(_params: lsp.InitializedParams) -> None:
     """Check jdtls availability; actual start deferred to first didOpen."""
     logger.info(
         "java-functional-lsp initialized (rules: %s)",
@@ -451,9 +528,7 @@ def _forward_or_queue(method: str, serialized: Any) -> None:
     if server._skip_jdtls:
         return
     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)
+        _fire_and_forget(server._proxy.send_notification(method, serialized))
     elif server._proxy._lazy_start_fired and not server._proxy._start_failed:
         server._proxy.queue_notification(method, serialized)
 
@@ -483,9 +558,7 @@ async def on_did_open(params: lsp.DidOpenTextDocumentParams) -> None:
         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)
+            _fire_and_forget(_lazy_start_jdtls(uri))
 
     # Custom diagnostics always publish immediately — never blocked by jdtls.
     try:
@@ -531,14 +604,21 @@ 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 and flushes
-    queued notifications. Workspace expansion is NOT done eagerly — modules
-    are loaded on-demand via ``add_module_if_new()`` as files are opened.
+    diagnostics.  After jdtls initializes, the workspace is immediately expanded
+    to the full IDE workspace root (inside-out) so jdtls discovers all sibling
+    modules before any queued ``didOpen`` notifications are flushed.  This means
+    ``add_module_if_new`` is a no-op for all subsequent file opens — jdtls
+    already covers the whole project.
     """
     try:
         started = await server._proxy.ensure_started(server._init_params, file_uri, config=server._config)
         if started:
             logger.info("jdtls proxy active — full Java language support enabled")
+            # Expand to full workspace BEFORE flushing queued notifications so
+            # all files are processed in the full-workspace context (inside-out).
+            # expand_full_workspace is a no-op for standalone projects where
+            # the workspace root equals the initial module.
+            await server._proxy.expand_full_workspace()
             if server._skip_jdtls_registration:
                 logger.info("Skipping dynamic capability registration (no-register mode)")
             else:
@@ -548,20 +628,6 @@ async def _lazy_start_jdtls(file_uri: str) -> None:
         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)
-
-
 # --- jdtls passthrough handlers (registered dynamically, NOT at module level) ---
 #
 # These are NOT decorated with @server.feature because pygls auto-advertises