feat: add requires_file_on_disk protocol for backend-specific file handling

Add LSPBackend.requires_file_on_disk() protocol method to allow backends
to declare whether they need files written to disk for analysis. This
fixes ty backend which cannot analyze virtual documents without
corresponding files on disk.

Changes:
- Add requires_file_on_disk() to LSPBackend protocol
- Implement in PyrightBackend (False), PyreflyBackend (False), TyBackend (True)
- Session.create() now writes initial code to disk when required
- Session.update_code() keeps disk files in sync
- Update tests to use tmp_path/base_path to avoid stray files in project root
- Remove xfails for ty tests that now pass (diagnostics, completion, rename, recycling)
- Update ty KNOWN_LIMITATIONS.md to document automatic handling

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: Mazyod

lsp_types/pyrefly/backend.py

@@ -84,3 +84,7 @@ def get_workspace_settings(
     def get_semantic_tokens_legend(self) -> types.SemanticTokensLegend | None:
         """Pyrefly doesn't advertise legend via LSP, return hardcoded legend."""
         return PYREFLY_LEGEND
+
+    def requires_file_on_disk(self) -> bool:
+        """Pyrefly supports virtual documents, no file needed on disk."""
+        return False

lsp_types/pyright/backend.py

@@ -83,3 +83,7 @@ def get_workspace_settings(
     def get_semantic_tokens_legend(self) -> types.SemanticTokensLegend | None:
         """Pyright advertises legend via LSP, use server-provided."""
         return None
+
+    def requires_file_on_disk(self) -> bool:
+        """Pyright supports virtual documents, no file needed on disk."""
+        return False

lsp_types/session.py

@@ -36,6 +36,15 @@ def get_semantic_tokens_legend(self) -> types.SemanticTokensLegend | None:
         """Return hardcoded legend if server doesn't advertise one."""
         ...
 
+    def requires_file_on_disk(self) -> bool:
+        """Return True if this backend requires files to exist on disk.
+
+        Some LSP backends (like ty) cannot analyze virtual documents opened via
+        didOpen without a corresponding file on disk. For these backends, the
+        session will write the initial code to disk before opening the document.
+        """
+        ...
+
 
 @dc.dataclass(kw_only=True)
 class DiagnosticsResult:
@@ -118,6 +127,11 @@ async def create_lsp_process():
                 workspace_settings
             )
 
+            # Write file to disk if backend requires it (e.g., ty)
+            if backend.requires_file_on_disk():
+                session._file_path.write_text(initial_code)
+                session._file_on_disk = True
+
             # Simulate opening a document
             await session._open_document(initial_code)
 
@@ -139,11 +153,13 @@ def __init__(
     ):
         self._process = lsp_process
         self._backend = backend
-        self._document_uri = f"file://{base_path / 'new.py'}"
+        self._file_path = base_path / "new.py"
+        self._document_uri = f"file://{self._file_path}"
         self._document_version = 1
         self._document_text = ""
         self._active_pool: LSPProcessPool | None = pool
         self._diag_result: DiagnosticsResult | None = None
+        self._file_on_disk = False  # Set to True if file was written for backends that require it
 
         # Semantic tokens normalization
         self._backend_legend = legend
@@ -170,6 +186,10 @@ async def update_code(self, code: str) -> int:
         self._document_version += 1
         self._document_text = code
 
+        # Keep file on disk in sync if required by backend
+        if self._file_on_disk:
+            self._file_path.write_text(code)
+
         document_version = self._document_version
         await self._process.notify.did_change_text_document(
             {

lsp_types/ty/KNOWN_LIMITATIONS.md

@@ -2,7 +2,7 @@
 
 This document describes known limitations and behavioral differences when using the ty backend compared to other LSP backends (Pyright, Pyrefly).
 
-## 1. Files Must Exist on Disk
+## 1. Files Must Exist on Disk (Handled Automatically)
 
 **Limitation**: ty requires Python files to exist on disk before it can provide diagnostics, completion, rename, and other analysis features.
 
@@ -11,23 +11,9 @@ This document describes known limitations and behavioral differences when using
 - Empty or limited completion results
 - Rename operations may fail
 
-**Workaround**: Always write files to disk before creating a session:
-```python
-from pathlib import Path
+**Resolution**: The `TyBackend` implements `requires_file_on_disk() -> True`, which tells `Session.create()` to automatically write the initial code to disk before opening the document. The `update_code()` method also keeps the file in sync with code changes.
 
-base_path = Path("/tmp/my_project")
-base_path.mkdir(exist_ok=True)
-
-code = "x: int = 'not an int'"
-(base_path / "new.py").write_text(code)
-
-session = await Session.create(
-    TyBackend(),
-    base_path=base_path,
-    initial_code=code,
-)
-diagnostics = await session.get_diagnostics()  # Now returns errors
-```
+This is handled transparently - no user action required.
 
 ## 2. `workspace/didChangeConfiguration` Not Supported
 
@@ -82,6 +68,17 @@ WARN Your LSP client doesn't support file watching: You may see stale results wh
 
 **Impact**: If files are modified outside the LSP session (e.g., by external tools), ty may not detect the changes until the session is recreated.
 
+## 7. Completion Item Resolution Not Supported
+
+**Limitation**: ty does not support the `completionItem/resolve` LSP request.
+
+**Behavior**: Calling `resolve_completion()` will raise an error:
+```
+Unknown request: completionItem/resolve (-32601)
+```
+
+**Impact**: Completion items won't have extended documentation or additional metadata that resolution typically provides. Basic completion works fine.
+
 ---
 
 ## Version Information

lsp_types/ty/backend.py

@@ -109,3 +109,7 @@ def get_workspace_settings(
     def get_semantic_tokens_legend(self) -> types.SemanticTokensLegend | None:
         """ty advertises legend via LSP, use server-provided."""
         return None
+
+    def requires_file_on_disk(self) -> bool:
+        """ty requires files to exist on disk for analysis."""
+        return True