docs: add language configuration guide and refactor project root discovery

Author: observerw

docs/language-configuration.md

@@ -0,0 +1,56 @@
+# Language Configuration Guide
+
+In the `lsp-client` SDK, language-specific configurations are primarily defined through the `LanguageConfig` class. This configuration determines how the client identifies files of a specific language, locates project roots, and interacts with the Language Server.
+
+## LanguageConfig
+
+`LanguageConfig` is an immutable configuration class defined in `lsp_client.client.lang`. it contains the following core fields:
+
+- **kind (`lsp_type.LanguageKind`)**:
+  Specifies the type of programming language (e.g., `Python`, `Rust`, `Go`, `TypeScript`). This typically corresponds to the language identifier in the LSP protocol.
+- **suffixes (`list[str]`)**:
+  A list of file extensions associated with the language (e.g., `[".py", ".pyi"]`). The client uses these suffixes to determine if a file belongs to this language.
+- **project_files (`list[str]`)**:
+  A list of "marker" files used to identify the project root directory (e.g., `["pyproject.toml", "Cargo.toml", "package.json"]`). When the client attempts to determine the root directory for a file, it searches upwards recursively for directories containing these files.
+- **exclude_files (`list[str]`)**:
+  A list of marker files indicating that a directory should _not_ be considered a project root.
+
+## Project Root Discovery
+
+The client determines the project root by searching upwards from the given file path until a valid project root is found or the system root is reached. This discovery is based on the `project_files` and `exclude_files` defined in the `LanguageConfig`.
+
+The `LanguageConfig` class provides a `find_project_root(path: Path)` method that combines `suffixes`, `project_files`, and `exclude_files` for precise detection.
+
+## Client Language Attributes
+
+The `Client` base class includes several general configurations related to language processing and server interaction:
+
+- **`sync_file` (bool, default `True`)**:
+  Whether to automatically synchronize file content with the server. If enabled, the client automatically sends `textDocument/didOpen` and `textDocument/didClose` notifications when using the `open_files` context manager.
+- **`initialization_options` (dict)**:
+  Custom options passed to the server during the `initialize` request. Most Language Servers require specific configurations here to function correctly.
+- **`request_timeout` (float, default `5.0`)**:
+  The timeout in seconds for LSP requests.
+
+## Example: Defining a Custom Language Client
+
+To support a new language, you typically inherit from `Client` (or a base class like `PythonClientBase`) and implement the `get_language_config` method:
+
+```python
+from pathlib import Path
+from typing import override
+from lsp_client.client.abc import Client
+from lsp_client.client.lang import LanguageConfig
+from lsp_client.utils.types import lsp_type
+
+class MyNewLanguageClient(Client):
+    @override
+    def get_language_config(self) -> LanguageConfig:
+        return LanguageConfig(
+            kind=lsp_type.LanguageKind.PlainText, # Replace with actual language kind
+            suffixes=[".mylang"],
+            project_files=["my_project.config"]
+        )
+
+    # Other abstract methods like create_default_servers must also be implemented
+```

src/lsp_client/client/abc.py

@@ -97,18 +97,6 @@ def get_workspace(self) -> Workspace:
     def get_server(self) -> Server:
         return self._server
 
-    @classmethod
-    @abstractmethod
-    def check_project_root(cls, path: Path) -> bool:
-        """Check if the given path is a project root for this client."""
-
-    @classmethod
-    def find_project_root(cls, path: Path) -> Path | None:
-        """Find the project root for the given path by searching upwards."""
-        for parent in [path, *path.parents]:
-            if cls.check_project_root(parent):
-                return parent
-
     @abstractmethod
     def get_language_config(self) -> LanguageConfig:
         """Get language-specific configuration for this client."""

src/lsp_client/clients/base.py

@@ -1,7 +1,6 @@
 from __future__ import annotations
 
 from abc import ABC
-from pathlib import Path
 from typing import override
 
 from lsp_client.client.abc import Client
@@ -10,19 +9,6 @@
 
 
 class PythonClientBase(Client, ABC):
-    @classmethod
-    def check_project_root(cls, path: Path) -> bool:
-        return any(
-            (path / f).exists()
-            for f in (
-                "pyproject.toml",
-                "setup.py",
-                "setup.cfg",
-                "requirements.txt",
-                ".python-version",
-            )
-        )
-
     @override
     def get_language_config(self) -> LanguageConfig:
         return LanguageConfig(
@@ -39,10 +25,6 @@ def get_language_config(self) -> LanguageConfig:
 
 
 class RustClientBase(Client, ABC):
-    @classmethod
-    def check_project_root(cls, path: Path) -> bool:
-        return (path / "Cargo.toml").exists()
-
     @override
     def get_language_config(self) -> LanguageConfig:
         return LanguageConfig(
@@ -53,10 +35,6 @@ def get_language_config(self) -> LanguageConfig:
 
 
 class GoClientBase(Client, ABC):
-    @classmethod
-    def check_project_root(cls, path: Path) -> bool:
-        return (path / "go.mod").exists()
-
     @override
     def get_language_config(self) -> LanguageConfig:
         return LanguageConfig(
@@ -67,13 +45,6 @@ def get_language_config(self) -> LanguageConfig:
 
 
 class TypeScriptClientBase(Client, ABC):
-    @classmethod
-    def check_project_root(cls, path: Path) -> bool:
-        return any(
-            (path / f).exists()
-            for f in ("package.json", "tsconfig.json", "jsconfig.json")
-        )
-
     @override
     def get_language_config(self) -> LanguageConfig:
         return LanguageConfig(

src/lsp_client/clients/deno/client.py

@@ -2,7 +2,6 @@
 
 import shutil
 from functools import partial
-from pathlib import Path
 from subprocess import CalledProcessError
 from typing import override
 
@@ -138,10 +137,6 @@ class DenoClient(
     - VSCode Extension: https://marketplace.visualstudio.com/items?itemName=denoland.vscode-deno
     """
 
-    @classmethod
-    def check_project_root(cls, path: Path) -> bool:
-        return any((path / f).exists() for f in ("deno.json", "deno.jsonc"))
-
     @override
     def get_language_config(self) -> LanguageConfig:
         return LanguageConfig(