# rlsp-yaml
A YAML language server implementing the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) using [tower-lsp](https://github.com/ebkalderon/tower-lsp) and [saphyr](https://github.com/saphyr-rs/saphyr) for YAML parsing.
## Features
**Core editing support:**
- Hover information (with schema-aware descriptions and formatted examples)
- Completion (structural + schema-driven, with snippet support)
- Document symbols (outline view)
- Folding ranges
- Selection ranges (AST-based expand/shrink)
- On-type formatting (auto-indent after colons and block scalars)
- Rename symbol (anchors/aliases)
- Go-to-definition and find references (anchors/aliases)
- Document links (URL detection + `!include` file paths)
- Code actions (flow/block conversion, tab fix, unused anchor delete, quoted bool, block scalar)
- Code lens (schema title/URL at top of document)
- Semantic highlighting (keys, values, anchors, aliases, tags, comments)
**Validation:**
- YAML syntax errors
- Duplicate key detection
- Unused anchor warnings
- Flow style warnings
- Key ordering enforcement (opt-in)
- Custom tag validation (workspace settings + modeline)
- JSON Schema validation (required properties, type checking, enum constraints)
**Schema support:**
- Schema association via modeline (`# yaml-language-server: $schema=<url>`)
- Schema association via workspace settings (glob-based `schemas` mapping)
- Schema disable via `$schema=none` modeline
- HTTP schema fetching with caching and SSRF guards
- Deprecated property tagging in completions
- Multi-required snippet completion (inserts all missing required properties)
- Expected properties listed in diagnostic messages
**Infrastructure:**
- File watcher registration (reacts to external file changes)
- Workspace settings (`customTags`, `keyOrdering`, `schemas`)
## Architecture
Pure-function design: each feature module exports a function that takes text (and optionally parsed YAML or schema) and returns LSP types. The server layer (`server.rs`) handles document storage, schema caching, and delegates to these pure functions.
```text
src/
├── main.rs # Binary entry point
├── lib.rs # Module declarations
├── server.rs # LSP Backend + LanguageServer trait impl
├── parser.rs # YAML parsing (saphyr)
├── document_store.rs # In-memory document cache
├── schema.rs # JSON Schema types, fetching, caching
├── schema_validation.rs # Schema-driven diagnostics
├── validators.rs # Non-schema diagnostics (anchors, flow, keys)
├── completion.rs # Completion provider
├── hover.rs # Hover provider
├── symbols.rs # Document symbols
├── references.rs # Go-to-definition + find references
├── rename.rs # Rename symbol
├── folding.rs # Folding ranges
├── selection.rs # Selection ranges
├── code_actions.rs # Code actions
├── code_lens.rs # Code lens
├── document_links.rs # Document links / URL detection
├── on_type_formatting.rs # On-type formatting
└── semantic_tokens.rs # Semantic highlighting
```
## Building
```sh
cargo build # build
cargo test # run all tests (~660 tests)
cargo clippy # lint (pedantic + nursery, zero warnings)
cargo fmt # format
```
## Usage
The server communicates over stdio using the LSP protocol. Point your editor's LSP client at the binary:
```sh
cargo build --release
# binary at target/release/rlsp-yaml
```
**VS Code:** Use a generic LSP client extension and configure it to run the binary for YAML files.
**Neovim (nvim-lspconfig):**
```lua
vim.lsp.start({
name = "rlsp-yaml",
cmd = { "/path/to/rlsp-yaml" },
filetypes = { "yaml", "yml" },
})
```
## Configuration
Settings are passed via `initializationOptions` or `workspace/didChangeConfiguration`. Per-document modelines override workspace settings.
See [docs/configuration.md](docs/configuration.md) for the full reference — workspace settings, modelines, editor setup examples, and schema fetching details.
## License
[MIT](../LICENSE) — Christoph Dalski