emacs-lsp-proxy 0.5.5 → 0.5.7

package/README.md

@@ -1,7 +1,5 @@
 # LSP-PROXY (formerly LSP-COPILOT)
 
-*This project has been renamed from lsp-copilot to lsp-proxy to better reflect its core functionality as a communication proxy and aggregator between Emacs and multiple LSP servers. The name change does not affect the project's features or goals.*
-
 ## Introduction
 Lsp-Proxy is an LSP (Language Server Protocol) client for Emacs, implemented in Rust and inspired by [lsp-bridge](https://github.com/manateelazycat/lsp-bridge). It uses `jsonrpc.el` to facilitate communication between Emacs and the Lsp-Proxy Server. The Lsp-Proxy Server acts as an intermediary between Emacs and various language servers, handling communication with the language servers, processing the responses, and returning them to Emacs.
 
@@ -35,6 +33,7 @@ This will automatically install the appropriate binary for your platform (Linux
 
 ### Manually
 Before installing LSP-PROXY manually, you should install rust and cargo first.
+
 ```bash
 git clone https://github.com/jadestrong/emacs-lsp-proxy.git ./your-directory
 cd ./your-directory
@@ -50,6 +49,7 @@ You can download the prebuilt binary from [releases](https://github.com/jadestro
 > The application cannot be opened because it is from an unidentified developer. You can allow this app to run by going to System Settings > Privacy & Security and selecting 'Allow Anyway' for this app.
 
 ## How to use
+
 ```emacs-lisp
 (use-package lsp-proxy
   ;; :load-path "/path/to/lsp-proxy"
@@ -60,31 +60,184 @@ You can download the prebuilt binary from [releases](https://github.com/jadestro
   (add-hook 'typescript-ts-mode-hook #'lsp-proxy-mode))
 ```
 
+### DOOM Emacs
+- Recommend
+``` elisp
+(package! lsp-proxy :recipe (:host github :repo "jadestrong/lsp-proxy"
+                :files ("lsp-proxy.el"))
+```
+- Manually
 ```elisp
-;; Doom Emacs
+
 (package! lsp-proxy :recipe (:host github :repo "jadestrong/lsp-proxy"
                 :files ("lsp-proxy.el" "emacs-lsp-proxy")
                 :pre-build (("cargo" "build" "--release") ("cp" "./target/release/emacs-lsp-proxy" "./"))))
+```
 
-(set-lookup-handlers! 'lsp-proxy-mode
+``` elisp
+(use-package! lsp-proxy
+  :config
+  (set-lookup-handlers! 'lsp-proxy-mode
     :definition '(lsp-proxy-find-definition :async t)
     :references '(lsp-proxy-find-references :async t)
     :implementations '(lsp-proxy-find-implementations :async t)
     :type-definition '(lsp-proxy-find-type-definition :async t)
-    :documentation '(lsp-proxy-describe-thing-at-point :async t))
+    :documentation '(lsp-proxy-describe-thing-at-point :async t)))
+
 ```
 
-## Add a new language
-Performed simple tests on Windows 11 and Arch Linux, it works properly. I have tested it on macOS and use it for daily development in JavaScript, Rust, etc. Therefore, tools like vtsls, typescript-language-server, eslint, tailwindcss, css, and others work fine
-- JavaScript/Typescript: [vtsls](https://github.com/yioneko/vtsls) (built-in)、[typescript-language-server](https://github.com/typescript-language-server/typescript-language-server)
-- eslint、html、css、html: [vscode-langservers-extracted](https://github.com/hrsh7th/vscode-langservers-extracted) +the latest vscode-eslint has removed the publishDiagnostics method and only supports the pullDiagnostics method, so currently we can only use `vscode-langservers-extracted@4.8`+.
-- tailwindcss: [@tailwindcss/language-server](https://www.npmjs.com/package/@tailwindcss/language-server)
+## How to add a new language
+
+### Supported Language Servers
+
+**Built-in Support:**
+- **JavaScript/TypeScript**: [vtsls](https://github.com/yioneko/vtsls), [typescript-language-server](https://github.com/typescript-language-server/typescript-language-server)
+- **Web Technologies**: [vscode-langservers-extracted](https://github.com/hrsh7th/vscode-langservers-extracted) (eslint, html, css)
+- **CSS Framework**: [@tailwindcss/language-server](https://www.npmjs.com/package/@tailwindcss/language-server)
+- **Rust**: rust-analyzer
+- **Python**: basedpyright, pylsp
+- **Go**: gopls
+- And many more in the built-in configuration
+
+### Quick Setup Guide
+
+1. **Open configuration file**
+   ```elisp
+   M-x lsp-proxy-open-config-file
+   ```
+
+2. **Add language server definition**
+   ```toml
+   [language-server.your-server]
+   command = "your-language-server"     # Required: executable command
+   args = ["--stdio"]                   # Optional: command arguments
+   environment = { VAR = "value" }      # Optional: environment variables  
+   timeout = 20                         # Optional: request timeout (default: 20s)
+   config = { key = "value" }           # Optional: initializationOptions 
+   experimental = { key = "value" }     # Optional: experimental client capabilities., e.g. rust-analyzer
+   ```
+
+3. **Define language mapping**
+   ```toml
+   [[language]]
+   name = "your-language"               # Required: unique language name
+   language-id = "your-language"        # Required: LSP language identifier
+   file-types = ["ext1", "ext2"]        # Required: file extensions
+   roots = ["project-file.json"]        # Optional: project root detection files
+   language-servers = ["your-server"]   # Required: associated servers
+   ```
+   
+   The `language-servers` field can be a simple string array containing the server names you configured above. It can also be configured with detailed options. See the **Advanced Configuration** section for more information.
+   
+   **Note:** The language's name can be customized, but the `language-id` should correspond to the `file-types`. For example:
+   - `["js", "mjs", "cjs"]` files correspond to `javascript` language ID
+   - `[jsx]` files correspond to `javascriptreact` language ID  
+   - `[tsx]` files correspond to `typescriptreact` language ID
+
+4. **Restart LSP-Proxy**
+   ```elisp
+   M-x lsp-proxy-restart
+   ```
+
+### Advanced Configuration
+
+#### Multi-Server Setup
+Configure multiple language servers for a single language:
+```toml
+[[language]]
+name = "typescript"
+language-servers = [
+  { name = "vtsls", except-features = ["format"] },
+  { name = "eslint", support-workspace = true }
+]
+```
+
+You can configure multiple language servers together for a single file type. For example, you can use `vtsls`, `eslint`, and `tailwindcss` for TypeScript/JSX files, or `eslint`, `vue-language-server`, and `tailwindcss` for Vue files. 
+
+When multiple language servers support the same feature, you can control which server provides specific functionality by using `except-features` or `only-features`. For example, you can disable the `format` feature from the `vtsls` language server while keeping it enabled for other servers.
+
+#### Feature Control Options
+- **`except-features`**: Disable specific server capabilities. See the **Supported LSP Features** section for available features.
+- **`only-features`**: Enable only specified features (whitelist). See the **Supported LSP Features**  section for available features.
+- **`support-workspace`**: Enable multi-workspace support, allowing language servers like `eslint` to share a single server instance across multiple projects.
+- **`library-directories`**: Additional library search paths for external dependencies. Some language servers manage libraries outside the project directory (e.g., rust-analyzer uses `~/.cargo/registry/src` and `~/.rustup/toolchains`, Dart uses `~/.pub-cache`). Since these libraries are shared across multiple projects, LSP-Proxy needs to send proper notifications (like `didOpen`) to the associated language server when navigating to files in these directories.
+- **`config-files`**: Optional configuration files for server activation. When configured, the language server will only activate if at least one of the specified configuration files exists in the workspace root (e.g., `eslint.config.ts` for ESLint server, `vue.config.ts` for vue-language-server).
+
+#### Server Configuration Examples
 
-The configuration for a new language can refer to the [Helix configuration](https://github.com/helix-editor/helix/blob/master/languages.toml). Supported fields are based on [the built-in configuration file](https://github.com/jadestrong/lsp-copilot/blob/main/languages.toml), and only LSP-related fields are supported.
-Open custom language config file by `lsp-proxy-open-config-file` and add your config, then execute `lsp-proxy-restart`.
+There are two syntaxes for setting a language server's configuration. Your configured values will be passed to the language server in the `initialize` request's `initializationOptions` and will also be used for `workspace/configuration` requests.
 
-The configuration fields for adding language support are: `name、roots、language-id、file-types、language-servers` . Other fields in the Helix configuration are not supported.
+**Python with advanced configuration:**
+```toml
+[language-server.basedpyright]
+command = "basedpyright-langserver"
+args = ["--stdio"]
+config.basedpyright.analysis.typeCheckingMode = "basic"
 
+[[language]]
+name = "python"
+language-servers = [
+  { name = "basedpyright", library-directories = ["~/.local/lib/python3.*/site-packages"] }
+]
+```
+
+The following syntax is different from the above example, but achieves the same effect as long as it follows valid TOML syntax:
+``` toml
+[language-server.basedpyright.config.basedpyright]
+analysis.typeCheckingMode = "basic"
+```
+
+### Supported LSP Features
+
+LSP-Proxy supports all major Language Server Protocol features:
+
+**Navigation & References:**
+- `goto-declaration` - Jump to symbol declarations
+- `goto-definition` - Jump to symbol definitions  
+- `goto-type-definition` - Jump to type definitions
+- `goto-reference` - Find all references
+- `goto-implementation` - Find implementations
+
+**Code Intelligence:**
+- `completion` - Auto-completion with snippets
+- `inline-completion` - Inline completion suggestions
+- `completion-resolve` - Detailed completion information
+- `signature-help` - Function signature assistance
+- `hover` - Symbol documentation on hover
+- `document-highlight` - Symbol highlighting
+- `inlay-hints` - Inline type and parameter hints
+
+**Code Quality:**
+- `diagnostics` - Error and warning reporting
+- `pull-diagnostics` - On-demand diagnostic retrieval
+- `code-action` - Quick fixes and refactoring
+- `rename-symbol` - Symbol renaming across workspace
+- `format` - Code formatting
+
+**Workspace Features:**
+- `document-symbols` - File outline and structure
+- `workspace-symbols` - Project-wide symbol search
+- `workspace-command` - Execute workspace-specific commands
+
+### Configuration Sources
+
+LSP-Proxy uses a layered configuration system:
+
+1. **Built-in configuration**: Default language servers and settings
+2. **User configuration**: Custom overrides in `${user-emacs-directory}/lsp-proxy/languages.toml`, opened by `M-x lsp-proxy-open-config-file`
+3. **Deep merging**: User config merges with built-in defaults (3 levels deep)
+
+The configuration format is compatible with [Helix editor](https://github.com/helix-editor/helix/blob/master/languages.toml) language definitions, focusing on LSP-related fields only.
+
+### Troubleshooting
+
+- **Server not starting**: Check `command` path and `args` correctness
+- **No completions**: Verify `language-id` matches server expectations
+- **Project not detected**: Ensure `roots` files exist in your project
+- **Features missing**: Check server capabilities and `except-features` configuration
+- **Debug**: Use `M-x lsp-proxy-open-log-file` and set `(setq lsp-proxy-log-level 3)`
+
+## Example
 
 - Vue2:
 ```toml
@@ -102,46 +255,44 @@ language-servers = ["vls"]
 
 - Vue3
 ```sh
-yarn global add @vue/language-server @vue/typescript-plugin
+yarn global add @vue/language-server @vue/typescript-plugin typescript
 ```
 
 ```toml
+# typescript-language-server
 [language-server.typescript-language-server]
 config.plugins = [
-  { name = "@vue/typescript-plugin", location = "${your-path}/node_modules/@vue/typescript-plugin", languages = ["vue"]}
+  { name = "@vue/typescript-plugin", location = "${YOUR-PATH}/node_modules/@vue/typescript-plugin", languages = ["vue"], enableForWorkspaceTypeScriptVersions = true, configNamespace = "typescript" }
+]
+
+# or vtsls
+[language-server.vtsls.config.vtsls.tsserver]
+globalPlugins = [
+  { name = "@vue/typescript-plugin", location = "${YOUR-PATH}/node_modules/@vue/typescript-plugin", languages = ["vue"], enableForWorkspaceTypeScriptVersions = true, configNamespace = "typescript" }
 ]
 
 [language-server.vue-language-server]
 command = "vue-language-server"
 args = ["--stdio"]
-config.typescript = { tsdk = "${your-path}/node_modules/typescript/lib" }
-config.vue = { hybridMode = false }
 
 [[language]]
 name = "vue"
 roots = ["package.json"]
 language-id = "vue"
-file-types = ["vue", "ts"]
-language-servers = ["vue-language-server", "typescript-language-server"]
-
-# Override the build-in config. The built-in configuration uses vtsls, but it seems incompatible with vue-language-server. It could also be that my configuration is incorrect.
-# Others, such as JavaScript and TSX, can be added as needed.
-[[language]]
-name = "typescript"
-language-id = "typescript"
-file-types = ["ts", "mts", "cts"]
-roots = ["package.json"]
+file-types = ["vue"]
 language-servers = [
-  { name = "typescript-language-server", except-features = [
-    "format",
-  ] },
-  { name = "eslint", support-workspace = true, config-files = [".eslintrc.js", ".eslintrc.cjs", ".eslintrc.yaml", ".eslintrc.yml", ".eslintrc", ".eslintrc.json", , "eslint.config.js", "eslint.config.mjs", "eslint.config.cjs", "eslint.config.ts", "eslint.config.mts", "eslint.config.cts"] },
+  { name = "vue-language-server", except-features = ["goto-definition", "goto-implementation", "goto-type-definition", "goto-declaration", "goto-reference"] },
+  "vtsls"
 ]
+# or
+# language-servers = [
+#   { name = "vue-language-server", except-features = ["goto-definition", "goto-implementation", "goto-type-definition", "goto-declaration", "goto-reference"] },
+#   "typescript-language-server"
+# ]
 ```
 
-- `except-features` can disable server's feature, view the [supported features](https://github.com/jadestrong/lsp-copilot/blob/c3d314d9bc1778b35c6ad2a046fa8b76cad94db4/src/syntax.rs#L150-L168).
-
 ## Debug
+
 ### Server bug
 - `(setq lsp-proxy-log-level 3)`
 - M-x `lsp-proxy-restart`
@@ -229,4 +380,4 @@ Regarding the communication between Emacs and Lsp-Proxy, I would like to especia
 
 The various methods used to implement LSP-related functionality on the Emacs side were learned from [lsp-mode](https://github.com/emacs-lsp/lsp-mode) and [eglot](https://github.com/joaotavora/eglot). Without their guidance, many of these features would have been difficult to implement.
 
-Regarding the communication data format between Emacs and Lsp-Proxy, I would like to especially thank [emacs-lsp-booster](https://github.com/blahgeek/emacs-lsp-booster). The project integrates the implementation of emacs-lsp-booster, which encodes the JSON data returned to Emacs, further reducing the load on Emacs.
+Regarding the communication data format between Emacs and Lsp-Proxy, I would like to especially thank [emacs-lsp-booster](https://github.com/blahgeek/emacs-lsp-booster). The project integrates the implementation of emacs-lsp-booster, which encodes the JSON data returned to Emacs, further reducing the load on Emacs.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "emacs-lsp-proxy",
-  "version": "0.5.5",
+  "version": "0.5.7",
   "scripts": {
     "postinstall": "node ./install.js"
   },
@@ -17,11 +17,11 @@
   ],
   "author": "jadestrong",
   "optionalDependencies": {
-    "@emacs-lsp-proxy/darwin-x64": "0.5.5",
-    "@emacs-lsp-proxy/darwin-arm64": "0.5.5",
-    "@emacs-lsp-proxy/linux-x64": "0.5.5",
-    "@emacs-lsp-proxy/linux-arm64": "0.5.5",
-    "@emacs-lsp-proxy/win32-x64": "0.5.5"
+    "@emacs-lsp-proxy/darwin-x64": "0.5.7",
+    "@emacs-lsp-proxy/darwin-arm64": "0.5.7",
+    "@emacs-lsp-proxy/linux-x64": "0.5.7",
+    "@emacs-lsp-proxy/linux-arm64": "0.5.7",
+    "@emacs-lsp-proxy/win32-x64": "0.5.7"
   },
   "license": "ISC",
   "description": "An LSP client for Emacs implemented in Rust."