Skip to content

LSP Configuration

Jump to bottom
Mo Abualruz edited this page Dec 4, 2025 · 1 revision

LSP Configuration Guide

Status: ✅ Complete

Last Updated: December 4, 2025

Overview

This guide explains how to configure language support for the RiceCoder LSP server. Language configurations define how code is analyzed, what diagnostics are generated, and what code actions are available.

Configuration Hierarchy

Configurations are loaded in priority order:

  1. Runtime: Configuration passed via CLI or API (highest priority)
  2. Project-level: .agent/lsp/languages/ in project root
  3. User-level: ~/.ricecoder/lsp/languages/ in user home
  4. Built-in: Bundled with ricecoder-storage (lowest priority)

Later configurations override earlier ones, allowing project and user customization.

Configuration Format

Language configurations are YAML files with the following structure:

language: rust
file_extensions:
  - rs
  - rs.in

parser_plugin: tree-sitter-rust

diagnostic_rules:
  - name: unused_imports
    pattern: "use.*;"
    severity: warning
    message: "Unused import"
    fix_template: "Remove import"
    code: "unused-import"

code_actions:
  - name: add_doc_comment
    title: "Add documentation comment"
    kind: quickfix
    transformation: "Add /// comment above"

Configuration Fields

Top-level Fields

Field Type Required Description
language string Yes Language identifier (e.g., "rust", "typescript", "python")
file_extensions array Yes File extensions for this language (e.g., ["rs", "rs.in"])
parser_plugin string No Parser plugin reference (e.g., "tree-sitter-rust")
diagnostic_rules array No Diagnostic rules for this language
code_actions array No Code action transformations

Diagnostic Rule Fields

Field Type Required Description
name string Yes Rule name (unique identifier)
pattern string Yes Pattern to match (regex or simple pattern)
severity string Yes Severity level: "error", "warning", or "info"
message string Yes Diagnostic message shown to user
fix_template string No Template for fix suggestion
code string No Rule code for identification

Code Action Fields

Field Type Required Description
name string Yes Action name (unique identifier)
title string Yes Action title shown in editor
kind string Yes Action kind: "quickfix", "refactor", or "source"
transformation string Yes How to transform code

Built-in Configurations

Rust

File: ~/.ricecoder/lsp/languages/rust.yaml

Includes rules for:

  • Unused imports
  • Unused variables
  • Missing documentation

TypeScript

File: ~/.ricecoder/lsp/languages/typescript.yaml

Includes rules for:

  • Unused imports
  • Unused variables
  • Missing type annotations

Python

File: ~/.ricecoder/lsp/languages/python.yaml

Includes rules for:

  • Unused imports
  • Unused variables
  • Missing docstrings

Adding a New Language

Step 1: Create Configuration File

Create ~/.ricecoder/lsp/languages/{language}.yaml:

language: go
file_extensions:
  - go

parser_plugin: tree-sitter-go

diagnostic_rules:
  - name: unused_imports
    pattern: "^import"
    severity: warning
    message: "Unused import"

code_actions:
  - name: organize_imports
    title: "Organize imports"
    kind: source
    transformation: "Sort and group imports"

Step 2: Restart LSP Server

ricecoder lsp start

Step 3: Verify Configuration

Open a Go file and verify diagnostics appear.

Customizing Built-in Languages

To customize a built-in language, create a project-level configuration:

mkdir -p .agent/lsp/languages
cp ~/.ricecoder/lsp/languages/rust.yaml .agent/lsp/languages/rust.yaml

Edit .agent/lsp/languages/rust.yaml to customize rules.

Validation

Configurations are validated on load:

  • Language name must not be empty
  • At least one file extension required
  • Diagnostic rule names must be unique
  • Severity levels must be valid ("error", "warning", "info")
  • Action kinds must be valid ("quickfix", "refactor", "source")

Invalid configurations are rejected with clear error messages.

Examples

Example 1: Minimal Configuration

language: minimal
file_extensions:
  - min

Example 2: Full Configuration

language: example
file_extensions:
  - ex
  - example

parser_plugin: tree-sitter-example

diagnostic_rules:
  - name: rule1
    pattern: "pattern1"
    severity: error
    message: "Error message"
    fix_template: "Fix template"
    code: "E001"

  - name: rule2
    pattern: "pattern2"
    severity: warning
    message: "Warning message"

code_actions:
  - name: action1
    title: "Action 1"
    kind: quickfix
    transformation: "Transform code"

  - name: action2
    title: "Action 2"
    kind: refactor
    transformation: "Refactor code"

Example 3: Project-specific Configuration

Create .agent/lsp/languages/rust.yaml to override built-in Rust configuration:

language: rust
file_extensions:
  - rs
  - rs.in

parser_plugin: tree-sitter-rust

diagnostic_rules:
  # Custom rules for this project
  - name: project_specific_rule
    pattern: "TODO"
    severity: info
    message: "TODO comment found"

Troubleshooting

Configuration Not Loading

Problem: Configuration file is not being loaded

Solution:

  • Verify file is in correct location
  • Check file format is valid YAML
  • Verify file extension is .yaml or .yml
  • Check file permissions are readable

Invalid Configuration Error

Problem: "Validation error: ..." message

Solution:

  • Check all required fields are present
  • Verify severity levels are valid
  • Verify action kinds are valid
  • Check for typos in field names

Diagnostics Not Appearing

Problem: Diagnostics are not shown for configured language

Solution:

  • Verify file extension matches configuration
  • Check diagnostic rules are not empty
  • Verify pattern is valid regex
  • Restart LSP server

See Also

Last updated: December 4, 2025

Clone this wiki locally