perf: parallelize LSP deadcode analysis and add reference cache

- Parallelize accurate deadcode symbol checks with asyncio.gather + semaphore(15)
- Add 5-min TTL reference cache to AuroraLSPClient to avoid re-querying same symbols
- Cache empty results too (avoids repeated lookups for dead symbols)
- clear_ref_cache() and auto-clear on close()

Author: hamr0

packages/lsp/src/aurora_lsp/analysis.py

@@ -5,6 +5,7 @@
 
 from __future__ import annotations
 
+import asyncio
 import json
 import logging
 import subprocess
@@ -607,30 +608,31 @@ async def find_dead_code(
         dead = []
 
         if accurate:
-            # Phase 2 (accurate): LSP references for each symbol (95%+ accuracy, slower)
+            # Phase 2 (accurate): LSP references for each symbol (95%+ accuracy)
+            # Parallelized with semaphore to avoid overwhelming the language server
             logger.info(f"Accurate mode: checking {len(all_symbols)} symbols via LSP references")
-            for sym in all_symbols:
-                try:
-                    # Get usages via LSP (excludes imports automatically)
-                    result = await self.find_usages(
-                        sym["file"], sym["line"], sym.get("col", 10), include_imports=False
-                    )
-                    usage_count = result.get("total_usages", 0)
+            semaphore = asyncio.Semaphore(15)
 
-                    # Dead if 0 usages (definition itself is not counted as usage)
-                    if usage_count == 0:
-                        dead.append(
-                            {
+            async def _check_symbol(sym: dict) -> dict | None:
+                async with semaphore:
+                    try:
+                        result = await self.find_usages(
+                            sym["file"], sym["line"], sym.get("col", 10), include_imports=False
+                        )
+                        if result.get("total_usages", 0) == 0:
+                            return {
                                 "file": sym["file"],
                                 "line": sym["line"],
                                 "name": sym["name"],
                                 "kind": SymbolKind(sym["kind"]).name.lower(),
                                 "imports": result.get("total_imports", 0),
                             }
-                        )
-                except Exception as e:
-                    logger.debug(f"LSP reference check failed for {sym['name']}: {e}")
-                    continue
+                    except Exception as e:
+                        logger.debug(f"LSP reference check failed for {sym['name']}: {e}")
+                    return None
+
+            results = await asyncio.gather(*[_check_symbol(sym) for sym in all_symbols])
+            dead = [r for r in results if r is not None]
         else:
             # Phase 2 (fast): ONE batched ripgrep call for ALL symbols (80-85% accuracy)
             symbol_names = list(set(s["name"] for s in all_symbols))

packages/lsp/src/aurora_lsp/client.py

@@ -7,6 +7,7 @@
 
 import asyncio
 import logging
+import time
 from pathlib import Path
 from typing import Any
 
@@ -60,6 +61,9 @@ def __init__(self, workspace: Path | str):
         self._lock = asyncio.Lock()
         self._logger: Any = None
         self._started = False
+        # Reference cache: (rel_path, line, col) -> (timestamp, results)
+        self._ref_cache: dict[tuple[str, int, int], tuple[float, list[dict]]] = {}
+        self._ref_cache_ttl: float = 300.0  # 5 minutes
 
         # Initialize language map if multilspy is available
         if MULTILSPY_AVAILABLE and Language is not None:
@@ -160,6 +164,9 @@ async def request_references(
     ) -> list[dict]:
         """Find all references to a symbol.
 
+        Results are cached by (file_path, line, col) with a 5-minute TTL so
+        repeated deadcode runs or overlapping symbol checks reuse prior results.
+
         Args:
             file_path: Path to file containing the symbol.
             line: Line number (0-indexed).
@@ -168,8 +175,20 @@ async def request_references(
         Returns:
             List of reference locations, each with 'file', 'line', 'col' keys.
         """
-        server = await self._ensure_server(file_path)
         rel_path = self._to_relative(file_path)
+        cache_key = (rel_path, line, col)
+
+        # Check cache
+        cached = self._ref_cache.get(cache_key)
+        if cached is not None:
+            ts, results = cached
+            if (time.monotonic() - ts) < self._ref_cache_ttl:
+                logger.debug(f"Reference cache hit for {rel_path}:{line}:{col}")
+                return results
+            # Expired — remove stale entry
+            del self._ref_cache[cache_key]
+
+        server = await self._ensure_server(file_path)
         self._ensure_file_open(server, file_path)
 
         try:
@@ -180,6 +199,8 @@ async def request_references(
                     f"LSP returned 0 references for {rel_path}:{line}:{col} "
                     f"(language server may not fully support this file type)"
                 )
+            # Cache the result (including empty results to avoid re-querying)
+            self._ref_cache[cache_key] = (time.monotonic(), normalized)
             return normalized
         except Exception as e:
             logger.warning(f"request_references failed for {rel_path}:{line}:{col}: {e}")
@@ -273,6 +294,10 @@ async def request_diagnostics(
             logger.warning(f"request_diagnostics failed: {e}")
             return []
 
+    def clear_ref_cache(self) -> None:
+        """Clear the reference cache (e.g. after file modifications)."""
+        self._ref_cache.clear()
+
     async def close(self) -> None:
         """Close all language server connections."""
         async with self._lock:
@@ -295,6 +320,7 @@ async def close(self) -> None:
             self._servers.clear()
             self._contexts.clear()
             self._open_files.clear()
+            self._ref_cache.clear()
 
     def _to_relative(self, file_path: str | Path) -> str:
         """Convert absolute path to workspace-relative path."""

packages/lsp/tests/test_analysis_client.py

@@ -323,3 +323,109 @@ def test_to_relative_outside_workspace(self, tmp_path):
         client = self._make_client(tmp_path)
         result = client._to_relative("/completely/different/path.py")
         assert result == "/completely/different/path.py"
+
+
+# ---------------------------------------------------------------------------
+# Reference cache
+# ---------------------------------------------------------------------------
+
+
+class TestReferenceCache:
+    """Tests for in-memory reference cache on AuroraLSPClient."""
+
+    def _make_client(self, tmp_path):
+        client = AuroraLSPClient(workspace=tmp_path)
+        return client
+
+    @pytest.mark.asyncio
+    async def test_cache_hit_avoids_server_call(self, tmp_path):
+        """Second call with same args returns cached result without querying LSP."""
+        import time
+
+        client = self._make_client(tmp_path)
+
+        fake_server = AsyncMock()
+        fake_server.request_references = AsyncMock(
+            return_value=[
+                {
+                    "absolutePath": "/proj/foo.py",
+                    "range": {"start": {"line": 10, "character": 0}},
+                }
+            ]
+        )
+        fake_server.open_file = MagicMock(return_value=MagicMock())
+
+        with patch.object(client, "_ensure_server", return_value=fake_server):
+            result1 = await client.request_references("src/foo.py", 5, 0)
+            result2 = await client.request_references("src/foo.py", 5, 0)
+
+        # Server queried only once — second call served from cache
+        assert fake_server.request_references.call_count == 1
+        assert result1 == result2
+        assert len(result1) == 1
+
+    @pytest.mark.asyncio
+    async def test_cache_miss_different_location(self, tmp_path):
+        """Different (file, line, col) triggers a fresh LSP query."""
+        client = self._make_client(tmp_path)
+
+        fake_server = AsyncMock()
+        fake_server.request_references = AsyncMock(return_value=[])
+        fake_server.open_file = MagicMock(return_value=MagicMock())
+
+        with patch.object(client, "_ensure_server", return_value=fake_server):
+            await client.request_references("src/a.py", 1, 0)
+            await client.request_references("src/a.py", 2, 0)
+
+        assert fake_server.request_references.call_count == 2
+
+    @pytest.mark.asyncio
+    async def test_cache_expiry(self, tmp_path, monkeypatch):
+        """Expired entries are evicted and LSP is re-queried."""
+        import time as time_mod
+
+        client = self._make_client(tmp_path)
+        client._ref_cache_ttl = 0.0  # expire immediately
+
+        fake_server = AsyncMock()
+        fake_server.request_references = AsyncMock(return_value=[])
+        fake_server.open_file = MagicMock(return_value=MagicMock())
+
+        with patch.object(client, "_ensure_server", return_value=fake_server):
+            await client.request_references("src/a.py", 1, 0)
+            # TTL=0 means next call should miss cache
+            await client.request_references("src/a.py", 1, 0)
+
+        assert fake_server.request_references.call_count == 2
+
+    @pytest.mark.asyncio
+    async def test_cache_empty_results(self, tmp_path):
+        """Empty results are cached too (avoids re-querying dead symbols)."""
+        client = self._make_client(tmp_path)
+
+        fake_server = AsyncMock()
+        fake_server.request_references = AsyncMock(return_value=[])
+        fake_server.open_file = MagicMock(return_value=MagicMock())
+
+        with patch.object(client, "_ensure_server", return_value=fake_server):
+            r1 = await client.request_references("src/a.py", 1, 0)
+            r2 = await client.request_references("src/a.py", 1, 0)
+
+        assert r1 == r2 == []
+        assert fake_server.request_references.call_count == 1
+
+    def test_clear_ref_cache(self, tmp_path):
+        """clear_ref_cache() empties the cache dict."""
+        client = self._make_client(tmp_path)
+        client._ref_cache[("src/a.py", 1, 0)] = (0.0, [])
+        assert len(client._ref_cache) == 1
+        client.clear_ref_cache()
+        assert len(client._ref_cache) == 0
+
+    @pytest.mark.asyncio
+    async def test_close_clears_cache(self, tmp_path):
+        """close() clears reference cache along with other state."""
+        client = self._make_client(tmp_path)
+        client._ref_cache[("src/a.py", 1, 0)] = (0.0, [{"file": "x", "line": 0, "col": 0}])
+        await client.close()
+        assert len(client._ref_cache) == 0