formatting: add support for JuliaFormatter

This commit extends the formatting system to support multiple formatter
backends beyond Runic.jl. Users can now choose between preset formatters
("Runic" or "JuliaFormatter") or configure custom formatters with their
own executables.

The formatter configuration has been redesigned from a nested structure
(`formatter.runic.executable`) to a simpler top-level `formatter`
setting that accepts either:
- A preset name string: "Runic" or "JuliaFormatter"
- A custom formatter defined under `formatter.custom` with `executable`
  and optional `executable_range` fields

The preset names use proper package names for clarity, while executables
remain as `runic`/`jlfmt` to match the actual binary names.

Due to limitations in Configurations.jl, custom formatters must be
specified in the `[formatter.custom]` section rather than directly as
the `formatter` value. Custom formatters can specify separate
executables for document and range formatting operations.

Additionally, `FormattingOptions` from LSP requests are now propagated
through the formatting pipeline, enabling formatters to respect
client-provided settings like tab size. For JuliaFormatter, the tab size
option is passed via the `--indent` flag. This client-wise setting will
be overwritten by .JuliaFormatter.toml configuration if it's found since
we are using the `--prioritize-config-file` option.

Requires domluna/JuliaFormatter.jl#947 to be merged.

Author: aviatesk

README.md

@@ -240,8 +240,8 @@ the list itself is subject to change.
   - [ ] Type of local binding on hover
 - Formatting
   - [x] [Runic](https://github.com/fredrikekre/Runic.jl) integration
-  - [ ] [JuliaFormatter](https://github.com/domluna/JuliaFormatter.jl) integration
-  - [ ] Make formatting backend configurable
+  - [x] [JuliaFormatter](https://github.com/domluna/JuliaFormatter.jl) integration
+  - [x] Make formatting backend configurable
 - Rename
   - [x] Local binding
   - [ ] Global binding
@@ -311,22 +311,32 @@ executable = "/custom/path/to/testrunner"
 
 See [TestRunner integration](#testrunner-integration) for setup instructions.
 
-#### `[formatter.runic] executable`
+#### `formatter`
 
-- Type: string (path)
-- Default: `"runic"` (or `"runic.bat"` on Windows)
+- Type: string or table
+- Default: `"Runic"`
 
-Path to the [Runic](https://github.com/fredrikekre/Runic.jl) formatter
-executable. If not specified, JETLS looks for `runic` in your `PATH` (typically
-`~/.julia/bin/runic`). Used for document formatting (triggered via editor
-format command).
+Configures the formatter backend for document and range formatting. Accepts
+either a preset formatter name or a custom formatter configuration.
 
-Example:
+Preset options:
+- `"Runic"` (default): Uses [Runic.jl](https://github.com/fredrikekre/Runic.jl)
+- `"JuliaFormatter"`: Uses [JuliaFormatter.jl](https://github.com/domluna/JuliaFormatter.jl)
+
+Examples:
 ```toml
-[formatter.runic]
-executable = "/custom/path/to/runic"
+# Use JuliaFormatter preset
+formatter = "JuliaFormatter"
+
+# Or use custom formatter (both fields optional)
+[formatter.custom]
+executable = "/path/to/custom-formatter"
+executable_range = "/path/to/custom-range-formatter"
 ```
 
+See [Formatting](#formatting) for detailed configuration instructions and setup
+requirements.
+
 ### How to configure
 
 #### Method 1: Project-specific configuration file
@@ -343,6 +353,9 @@ debounce = 2.0
 
 [testrunner]
 executable = "/custom/path/to/testrunner"
+
+# Use JuliaFormatter instead of Runic
+formatter = "JuliaFormatter"
 ```
 
 #### Method 2: Editor configuration via LSP
@@ -353,7 +366,7 @@ As examples, we show the configuration methods for the VSCode extension `jetls-c
 and the Zed extension [`aviatesk/zed-julia#avi/JETLS`](https://github.com/aviatesk/zed-julia/tree/avi/JETLS).
 
 ##### VSCode (`jetls-client` extension)
-Configure JETLS in Zed's settings.json file with `jetls-client.jetlsSettings` section:
+Configure JETLS in VSCode's settings.json file with `jetls-client.jetlsSettings` section:
 ```jsonc
 {
   "jetls-client.jetlsSettings": {
@@ -362,7 +375,8 @@ Configure JETLS in Zed's settings.json file with `jetls-client.jetlsSettings` se
     },
     "testrunner": {
       "executable": "/custom/path/to/testrunner"
-    }
+    },
+    "formatter": "JuliaFormatter"
   }
 }
 ```
@@ -387,7 +401,8 @@ Configure JETLS in Zed's settings.json file with the `lsp.JETLS.settings` sectio
         },
         "testrunner": {
           "executable": "/custom/path/to/testrunner"
-        }
+        },
+        "formatter": "JuliaFormatter"
       }
     }
   }
@@ -407,6 +422,99 @@ The `.JETLSConfig.toml` file takes precedence, since it provides a
 **client-agnostic** way to configure JETLS that works consistently across
 all editors.
 
+## Formatting
+
+JETLS provides document formatting support through integration with external
+formatting tools. By default, [Runic.jl](https://github.com/fredrikekre/Runic.jl)
+is used, but you can configure alternative formatters or use custom formatting
+executables.
+
+### Features
+
+- **Document formatting**: Format entire Julia files
+- **Range formatting**: Format selected code regions (Runic and custom
+  formatters only)
+- **Progress notifications**: Visual feedback during formatting operations
+  for clients that support work done progress
+
+### Prerequisites
+
+JETLS supports preset formatters as well as custom formatting executables.
+For preset formatters, install your preferred formatter and ensure it's
+available in your system `PATH`:
+- [Runic](https://github.com/fredrikekre/Runic.jl) (default):
+  ```bash
+  julia -e 'using Pkg; Pkg.Apps.add("Runic")'
+  ```
+- [JuliaFormatter](https://github.com/domluna/JuliaFormatter.jl):
+  ```bash
+  julia -e 'using Pkg; Pkg.Apps.add("JuliaFormatter")'
+  ```
+
+Note that you need to manually make `~/.julia/bin` available on the `PATH`
+environment for the formatter executables to be accessible.
+See <https://pkgdocs.julialang.org/dev/apps/> for the details.
+
+For custom formatters, no installation is required—simply configure the path
+to your executable in `.JETLSConfig.toml` (see the [custom formatter](#custom-formatter) section below).
+
+### Configuration
+
+Create a `.JETLSConfig.toml` file in your project root to configure the
+formatter. The configuration supports three options:
+
+#### Preset: [Runic](https://github.com/fredrikekre/Runic.jl) (default)
+
+```toml
+formatter = "Runic"
+```
+
+This is the default setting and doesn't require explicit configuration.
+Runic supports both document and range formatting.
+
+#### Preset: [JuliaFormatter](https://github.com/domluna/JuliaFormatter.jl)
+
+```toml
+formatter = "JuliaFormatter"
+```
+
+If a [`.JuliaFormatter.toml` configuration](https://domluna.github.io/JuliaFormatter.jl/dev/config/)
+file is found in your project, JuliaFormatter will use those settings.
+Otherwise, it uses default settings with formatting options provided by the
+editor client (such as tab size) when available.
+
+> [!WARNING]
+> Note that JuliaFormatter currently, as of v2.2.0, only supports full document
+> formatting, not range formatting.
+
+#### Custom formatter
+
+```toml
+[formatter.custom]
+executable = "/path/to/custom-formatter"
+executable_range = "/path/to/custom-range-formatter"
+```
+
+Custom formatters should accept Julia code via stdin and output formatted
+code to stdout, following the same interface as `runic`:
+- `executable`: Command for full document formatting. The formatter should
+  read the entire Julia source code from stdin, format it completely, and
+  write the formatted result to stdout. The exit code should be 0 on success.
+- `executable_range`: Command for range formatting. The formatter should
+  accept a `--lines=START:END` argument to format only the specified line
+  range. It should read the entire document code from stdin and write the
+  _entire document code_ to stdout with only the specified region formatted.
+  The rest of the document must remain unchanged.
+
+### Troubleshooting
+
+If you see an error about the formatter not being found:
+1. Ensure you've installed the formatter as described above
+2. Check that the formatter executable is in your system PATH by running
+   `which runic` or `which jlfmt`
+3. For custom formatters, verify the executable path in `.JETLSConfig.toml`
+4. Restart your editor to ensure it picks up the updated PATH or configuration
+
 ## TestRunner integration
 
 JETLS integrates with [TestRunner.jl](https://github.com/aviatesk/TestRunner.jl)

package.json

@@ -108,19 +108,37 @@
               }
             },
             "formatter": {
-              "type": "object",
-              "properties": {
-                "runic": {
+              "oneOf": [
+                {
+                  "type": "string",
+                  "enum": [
+                    "Runic",
+                    "JuliaFormatter"
+                  ],
+                  "default": "Runic",
+                  "description": "Preset formatter to use. 'Runic' (default) or 'JuliaFormatter'."
+                },
+                {
                   "type": "object",
                   "properties": {
-                    "executable": {
-                      "type": "string",
-                      "default": "",
-                      "description": "Path to the Runic formatter executable. If empty, uses 'runic' from PATH."
+                    "custom": {
+                      "type": "object",
+                      "properties": {
+                        "executable": {
+                          "type": "string",
+                          "description": "Path to custom formatter executable for document formatting. The formatter should read Julia code from stdin and output formatted code to stdout. Optional."
+                        },
+                        "executable_range": {
+                          "type": "string",
+                          "description": "Path to custom formatter executable for range formatting. Should accept --lines=START:END argument. Optional."
+                        }
+                      }
                     }
                   }
                 }
-              }
+              ],
+              "default": "Runic",
+              "markdownDescription": "Formatter configuration. Can be a preset name ('Runic' or 'JuliaFormatter') or a custom formatter object. See [Formatting](https://github.com/aviatesk/JETLS.jl#formatting) for details."
             }
           }
         }