mirror of
https://github.com/oxc-project/oxc.git
synced 2026-09-14 19:36:11 +08:00
leaysgur
259 lines
16 KiB
Markdown
259 lines
16 KiB
Markdown
# oxc_language_server
|
|
|
|
This crate provides an [LSP](https://microsoft.github.io/language-server-protocol/) Server which is used inside an editor or IDE.
|
|
|
|
## Server Capabilities
|
|
|
|
- [Text Document Synchronization](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocument_synchronization): `FULL`,
|
|
- Workspace
|
|
- [Workspace Folders](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#workspaceFoldersServerCapabilities): `true`
|
|
- File Operations: `false`
|
|
|
|
### For oxlint
|
|
|
|
- [Workspace commands](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#workspace_executeCommand)
|
|
- `oxc.fixAll`, requires `{ uri: URL }` as command argument. Does safe fixes in `uri` file.
|
|
- [Code Actions Provider](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#codeActionKind):
|
|
- `quickfix`
|
|
- `source.fixAll.oxc`, behaves the same as `quickfix` only used when the `CodeActionContext#only` contains
|
|
`source.fixAll.oxc`.
|
|
- [Diagnostic Provider](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocument_pullDiagnostics)
|
|
- Only when [Diagnostics Refresh](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#diagnostic_refresh) is supported by your client
|
|
|
|
### For oxfmt
|
|
|
|
- [DocumentFormattingProvider](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocument_formatting)
|
|
|
|
## Workspace Options
|
|
|
|
These options can be passed with [initialize](#initialize), [workspace/didChangeConfiguration](#workspace/didChangeConfiguration) and [workspace/configuration](#workspace/configuration).
|
|
|
|
| Option Key | Value(s) | Default | Description |
|
|
| ------------------------- | --------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| `configPath` | `<string>` \| `null` | `null` | Path to a oxlint configuration file, passing a string will disable nested configuration |
|
|
| `tsConfigPath` | `<string>` \| `null` | `null` | Path to a TypeScript configuration file. If your `tsconfig.json` is not at the root, alias paths will not be resolve correctly for the `import` plugin |
|
|
| `unusedDisableDirectives` | `"allow" \| "warn"` \| "deny"` | `"allow"` | Define how directive comments like `// oxlint-disable-line` should be reported, when no errors would have been reported on that line anyway |
|
|
| `typeAware` | `<boolean>` \| `null` | `null` | Enables type-aware linting. When unset (`null`), uses the root config's `options.typeAware` value. |
|
|
| `disableNestedConfig` | `false` \| `true` | `false` | Disabled nested configuration and searches only for `configPath`. |
|
|
| `fixKind` | [fixKind values](#fixkind-values) | `safe_fix_or_suggestion` | The level of a possible fix for a diagnostic, will be applied for the complete workspace (diagnostic, code action, commands and more). |
|
|
| `rulesCustomization` | `Map<string, RulesCustomization>` | `<empty>` | Rules customization, overriding severity or autofix with `source.fixAll.oxc`. The map key is the rule name, example: `typescript/no-unused-vars` |
|
|
| `fmt.configPath` | `<string>` \| `null` | `null` | Path to a oxfmt configuration file, passing a string will disable nested configuration. When `null` is passed, the server will use `.oxfmtrc.json` and the workspace root |
|
|
| `fmt.disableNestedConfig` | `false` \| `true` | `false` | Disabled nested configuration and searches only for `fmt.configPath`. |
|
|
| Diagnostic Pull Mode | | | |
|
|
| `run` | `"onSave" \| "onType"` | `"onType"` | Should the server lint the files when the user is typing or saving. In Pull Mode, the editor requests the diagnostic. |
|
|
| Deprecated | | | |
|
|
| `fmt.experimental` | `true` \| `false` | `false` | (deprecated) Enables experimental formatting with `oxc_formatter` |
|
|
| `flags` | `Map<string, string>` | `<empty>` | (deprecated) Custom flags passed to the language server. |
|
|
|
|
### `fixKind` values:
|
|
|
|
- `"safe_fix"`
|
|
- `"safe_fix_or_suggestion"` (default)
|
|
- `"dangerous_fix"`
|
|
- `"dangerous_fix_or_suggestion"`
|
|
- `"none"`
|
|
- `"all"`
|
|
|
|
### `RulesCustomization` struct:
|
|
|
|
```ts
|
|
interface RulesCustomization {
|
|
// overriding the rule severity, when "off", the rule will not output diagnostics.
|
|
severity?: "off" | "warn" | "error" | "hint" | "info";
|
|
|
|
// allows to disable the autofix for a specific rule, even when the rule has a fix and the workspace `fixKind` allows it.
|
|
// the user code action `quickfix` will still be available, but the `source.fixAll.oxc` & `source.fixAllDangerous.oxc` will ignore the rule.
|
|
autofix?: boolean;
|
|
}
|
|
```
|
|
|
|
## Diagnostics Modes
|
|
|
|
Depending on the client, the server will push diagnostics, or will wait for a pull request from the client.
|
|
The server will prefer pull diagnostics when the client supports it and is also supporting [workspace/diagnostic/refresh](#workspacediagnosticrefresh).
|
|
|
|
## Supported LSP Specifications from Server
|
|
|
|
### [initialize](https://microsoft.github.io/language-server-protocol/specification#initialize)
|
|
|
|
Returns the [Server Capabilities](#server-capabilities).\
|
|
The client can pass the workspace options like following:
|
|
|
|
```json
|
|
{
|
|
"initializationOptions": [
|
|
{
|
|
"workspaceUri": "file://workspace-directory",
|
|
"options": {
|
|
"run": "onType",
|
|
"configPath": null,
|
|
"tsConfigPath": null,
|
|
"unusedDisableDirectives": "allow",
|
|
"typeAware": false,
|
|
"disableNestedConfig": false,
|
|
"fixKind": "safe_fix",
|
|
"rulesCustomization": {},
|
|
"fmt.configPath": null,
|
|
"fmt.disableNestedConfig": false,
|
|
}
|
|
}
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
#### Flags (deprecated)
|
|
|
|
- `key: disable_nested_config`: Disabled nested configuration and searches only for `configPath`
|
|
- `key: fix_kind`: see [FixKind values](#fixkind-values) for possible values
|
|
|
|
### [initialized](https://microsoft.github.io/language-server-protocol/specification#initialized)
|
|
|
|
When the client did not pass the workspace configuration in [initialize](#initialize), the server will request the configuration for every workspace with [workspace/configuration](#workspaceconfiguration).
|
|
The server will tell the client with [client/registerCapability](#clientregistercapability) to watch for `.oxlintrc.json` files or a custom `oxc.configPath`.
|
|
|
|
### [shutdown](https://microsoft.github.io/language-server-protocol/specification#shutdown)
|
|
|
|
The server will reset the diagnostics for all open files and send one or more [textDocument/publishDiagnostics](#textdocumentpublishdiagnostics) requests to the client.
|
|
|
|
### Workspace
|
|
|
|
#### [workspace/didChangeConfiguration](https://microsoft.github.io/language-server-protocol/specification#workspace_didChangeConfiguration)
|
|
|
|
The client can pass the workspace options like following:
|
|
|
|
```json
|
|
{
|
|
"settings": [
|
|
{
|
|
"workspaceUri": "file://workspace-directory",
|
|
"options": {
|
|
"run": "onType",
|
|
"configPath": null,
|
|
"tsConfigPath": null,
|
|
"unusedDisableDirectives": "allow",
|
|
"typeAware": false,
|
|
"disableNestedConfig": false,
|
|
"fixKind": "safe_fix",
|
|
"rulesCustomization": {},
|
|
"fmt.configPath": null,
|
|
"fmt.disableNestedConfig": false
|
|
}
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
When the client does not pass workspace options, the server will request them with [workspace/configuration](#workspace/configuration).
|
|
The server will revalidate or reset the diagnostics for all open files and send one or more [textDocument/publishDiagnostics](#textdocumentpublishdiagnostics) requests to the client.
|
|
|
|
When changing the `oxc.configPath` settings:
|
|
The server will tell clients with [client/registerCapability](#clientregistercapability) to watch for `.oxlintrc.json` files or a custom `oxc.configPath`.
|
|
The server will tell clients with [client/unregisterCapability](#clientunregistercapability) to stop watching for `.oxlintrc.json` files or a custom `oxc.configPath`.
|
|
|
|
#### [workspace/didChangeWatchedFiles](https://microsoft.github.io/language-server-protocol/specification#workspace_didChangeWatchedFiles)
|
|
|
|
The server expects this request when one oxlint configuration is changed, added or deleted.
|
|
When the server is using [Push Mode](#diagnostics-modes),
|
|
the server will revalidate the diagnostics for all open files and send one or more [textDocument/publishDiagnostics](#textdocumentpublishdiagnostics) requests to the client.
|
|
When the server is using [Pull Mode](#diagnostics-modes),
|
|
the server will tell the client to revalidate all diagnostics with [`workspace/diagnostic/refresh`](#workspacediagnosticrefresh).
|
|
|
|
#### [workspace/didChangeWorkspaceFolders](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#workspace_didChangeWorkspaceFolders)
|
|
|
|
The server expects this request when adding or removing workspace folders.
|
|
The server will request the specific workspace configuration, if the client supports it.
|
|
The server will tell clients with [client/registerCapability](#clientregistercapability) to watch for `.oxlintrc.json` files or a custom `oxc.configPath`.
|
|
The server will tell clients with [client/unregisterCapability](#clientunregistercapability) to stop watching for `.oxlintrc.json` files or a custom `oxc.configPath`.
|
|
When the server is using [Push Mode](#diagnostics-modes),
|
|
the server will revalidate the diagnostics for all open files and send one or more [textDocument/publishDiagnostics](#textdocumentpublishdiagnostics) requests to the client.
|
|
When the server is using [Pull Mode](#diagnostics-modes),
|
|
the server will tell the client to revalidate all diagnostics with [`workspace/diagnostic/refresh`](#workspacediagnosticrefresh).
|
|
|
|
#### [workspace/executeCommand](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#workspace_executeCommand)
|
|
|
|
Executes a [Command](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#workspace_executeCommand) if it exists. See [Server Capabilities](#server-capabilities)
|
|
|
|
### TextDocument
|
|
|
|
#### [textDocument/didOpen](https://microsoft.github.io/language-server-protocol/specification#textDocument_didOpen)
|
|
|
|
The server will cache the internal content of the text document.
|
|
When the server is using [Push Mode](#diagnostics-modes), the server will validate the text document and send a [textDocument/publishDiagnostics](#textdocumentpublishdiagnostics) request to the client.
|
|
|
|
#### [textDocument/didSave](https://microsoft.github.io/language-server-protocol/specification#textDocument_didSave)
|
|
|
|
When the server is using [Push Mode](#diagnostics-modes) and configuration `run` is set to `onSave`,
|
|
the server will validate the text document and send a [textDocument/publishDiagnostics](#textdocumentpublishdiagnostics) request to the client.
|
|
|
|
#### [textDocument/didChange](https://microsoft.github.io/language-server-protocol/specification#textDocument_didChange)
|
|
|
|
The server will cache the internal content of the text document.
|
|
When the server is using [Push Mode](#diagnostics-modes) and configuration `run` is set to `onType`,
|
|
the server will validate the text document and send a [textDocument/publishDiagnostics](#textdocumentpublishdiagnostics) request to the client.
|
|
|
|
#### [textDocument/didClose](https://microsoft.github.io/language-server-protocol/specification#textDocument_didClose)
|
|
|
|
It will remove the reference internal.
|
|
|
|
#### [textDocument/codeAction](https://microsoft.github.io/language-server-protocol/specification#textDocument_codeAction)
|
|
|
|
Returns a list of [CodeAction](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocument_codeAction)
|
|
|
|
#### [textDocument/diagnostics](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocument_diagnostic)
|
|
|
|
Should only be used when the server is using the [Pull Mode](#diagnostics-modes) for diagnostics.
|
|
The server will lint the file and report the diagnostics back to the client.
|
|
|
|
#### [textDocument/formatting](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocument_formatting)
|
|
|
|
Returns a list of [TextEdit](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textEdit)
|
|
|
|
## Optional LSP Specifications from Client
|
|
|
|
### Client
|
|
|
|
#### [textDocument/publishDiagnostics](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocument_publishDiagnostics)
|
|
|
|
When the server is using [Push Mode](#diagnostics-modes) it will lint the file [onOpen](#textdocumentdidopen) and [onChange](#textdocumentdidchange) or [onSave](#textdocumentdidsave)
|
|
(depending on the configuration the client passed).
|
|
|
|
#### [workspace/diagnostic/refresh](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#diagnostic_refresh)
|
|
|
|
When the server is using the [Pull Mode](#diagnostics-modes) it will request the client sometimes to re-pull the diagnostics.
|
|
This will happen when changing watched files or specific server configurations.
|
|
|
|
#### [client/registerCapability](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#client_registerCapability)
|
|
|
|
The server will send this request to watch for specific files. The method `workspace/didChangeWatchedFiles` will be used with custom `registerOptions`.
|
|
|
|
#### [client/unregisterCapability](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#client_unregisterCapability)
|
|
|
|
The server will send this request to stop watching for specific files. The `id` will match from [client/registerCapability](#clientregistercapability).
|
|
|
|
### Workspace
|
|
|
|
#### [workspace/configuration](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#workspace_configuration)
|
|
|
|
The server will request workspace configurations. The server expects the received items to match the order of the requested items.
|
|
Only will be requested when the `ClientCapabilities` has `workspace.configuration` set to true.
|
|
|
|
The client can return a response like:
|
|
|
|
```json
|
|
[
|
|
{
|
|
"run": "onType",
|
|
"configPath": null,
|
|
"tsConfigPath": null,
|
|
"unusedDisableDirectives": "allow",
|
|
"typeAware": false,
|
|
"disableNestedConfig": false,
|
|
"fixKind": "safe_fix",
|
|
"rulesCustomization": {},
|
|
"fmt.configPath": null,
|
|
"fmt.disableNestedConfig": false
|
|
}
|
|
]
|
|
```
|