Skip to content

IDE Integration

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

IDE Integration

Status: ✅ Complete

Phase: Phase 2

Last Updated: December 9, 2025

Overview

The IDE Integration module connects ricecoder to popular IDEs and editors (VS Code, vim, neovim, emacs). Ricecoder queries external LSP servers for semantic intelligence and passes results to IDE extensions. This enables IDE users to access ricecoder's AI-powered features while leveraging specialized, maintained language tools.

Key Principle: Ricecoder does NOT implement LSP servers. Instead, it integrates with external LSP servers (rust-analyzer, typescript-language-server, pylsp) and passes their semantic intelligence to IDEs.

Key Features

  • External LSP-First Architecture: Prioritizes external LSP servers for semantic intelligence
  • Graceful Fallback Chain: Falls back through configured rules → built-in providers → generic features
  • Hot-Reload Support: Configuration and provider availability changes without restart
  • Multi-IDE Support: VS Code, vim, neovim, emacs integrations
  • IDE-Specific Configuration: Per-IDE settings and customization
  • Clear Error Messages: Configuration validation with remediation steps

Architecture

Provider Priority Chain

The IDE integration uses a priority-based provider chain to deliver semantic intelligence:

1. External LSP Servers (rust-analyzer, typescript-language-server, pylsp)
   ↓ (If unavailable or fails)
2. Configured IDE Rules (YAML/JSON configuration files)
   ↓ (If unavailable or fails)
3. Built-in Language Providers (Rust, TypeScript, Python)
   ↓ (If unavailable or fails)
4. Generic Text-Based Features (Fallback for any language)

System Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                         IDE Extensions Layer                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌────────────┐  │
│  │  VS Code     │  │  Vim/Neovim  │  │  Emacs       │  │  Other     │  │
│  │  Extension   │  │  Plugin      │  │  Integration │  │  IDEs      │  │
│  └──────────────┘  └──────────────┘  └──────────────┘  └────────────┘  │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                    IDE-specific communication protocols
                    (JSON-RPC, stdio, sockets, etc.)
                                    │
┌─────────────────────────────────────────────────────────────────────────┐
│                    IDE Integration Manager                               │
│  ┌──────────────────────────────────────────────────────────────────┐  │
│  │  IDE Request Handler                                             │  │
│  │  - Receives requests from IDE extensions                         │  │
│  │  - Routes to appropriate provider chain                          │  │
│  │  - Formats responses for IDE consumption                         │  │
│  └──────────────────────────────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────────────────────────────┐  │
│  │  Provider Chain Manager                                          │  │
│  │  - Priority 1: External LSP Servers                              │  │
│  │  - Priority 2: Configured IDE Rules                              │  │
│  │  - Priority 3: Built-in Language Providers                       │  │
│  │  - Priority 4: Generic Text-based Features                       │  │
│  └──────────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
┌─────────────────────────────────────────────────────────────────────────┐
│                    External LSP Integration Layer                        │
│  ┌──────────────────────────────────────────────────────────────────┐  │
│  │  ricecoder-external-lsp (Tier 1 Support)                         │  │
│  │  - rust-analyzer (Rust)                                          │  │
│  │  - typescript-language-server (TypeScript/JavaScript)            │  │
│  │  - pylsp (Python)                                                │  │
│  │  - Process management, health checks, restart policies           │  │
│  └──────────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────┘

Supported IDEs

VS Code

Native VS Code extension with full integration:

  • Completion provider
  • Diagnostics provider
  • Hover information
  • Definition navigation
  • Command palette integration
  • Settings integration

Status: ✅ Complete

See: VS Code Extension Guide

Vim / Neovim

Plugin support for vim and neovim:

  • Completion integration
  • Diagnostics display
  • Hover information
  • Definition navigation
  • Plugin manager support (vim-plug, packer, lazy.nvim)

Status: ✅ Complete

See: Terminal Editor Integration Guide

Emacs

Integration for emacs:

  • Completion support
  • Diagnostics display
  • Hover information
  • Definition navigation
  • Package manager support (use-package, straight.el)

Status: ✅ Complete

See: Terminal Editor Integration Guide

Configuration

Configuration File Location

IDE integration configuration is loaded from (in priority order):

  1. Runtime overrides (CLI flags, API calls)
  2. IDE-specific settings (VS Code settings.json, vim config, emacs config)
  3. Project-level configuration: projects/ricecoder/config/ide-integration.yaml
  4. User-level configuration: ~/.ricecoder/ide-integration.yaml
  5. Built-in defaults

Configuration Format

Configuration uses YAML format for human readability:

# IDE Integration Configuration
vscode:
  enabled: true
  port: 8080
  features:
    - completion
    - diagnostics
    - hover
    - definition
  settings:
    timeout_ms: 5000
    max_results: 50

terminal:
  vim:
    enabled: true
    plugin_manager: vim-plug
  neovim:
    enabled: true
    plugin_manager: lazy.nvim
  emacs:
    enabled: true
    package_manager: use-package

providers:
  external_lsp:
    enabled: true
    health_check_interval_ms: 5000
    servers:
      rust:
        language: rust
        command: rust-analyzer
        timeout_ms: 10000
      typescript:
        language: typescript
        command: typescript-language-server
        args: ["--stdio"]
        timeout_ms: 10000
      python:
        language: python
        command: pylsp
        timeout_ms: 10000
  
  configured_rules:
    enabled: true
    rules_path: config/ide-rules.yaml
  
  builtin_providers:
    enabled: true
    languages:
      - rust
      - typescript
      - python

Configuration Validation

All configuration is validated on load:

  • Required fields are checked
  • Field values are validated
  • Invalid configuration is rejected with clear error messages
  • Error messages include remediation steps

Example Error Message:

Configuration Error: Invalid value for 'providers.external_lsp.health_check_interval_ms'
  Expected: positive integer (milliseconds)
  Got: -1000
  Remediation: Set to a positive value (e.g., 5000 for 5 seconds)

IDE Features

Code Completion

Provides intelligent code completion suggestions:

  • Source: External LSP servers (primary), configured rules, built-in providers
  • Trigger: Automatic on typing or manual (Ctrl+Space)
  • Features: Snippet expansion, documentation, type information
  • Fallback: Generic word-based completion

Diagnostics

Displays code issues and errors:

  • Source: External LSP servers (primary), configured rules, built-in providers
  • Display: Inline in editor, problems panel
  • Features: Error/warning/info levels, quick fixes
  • Fallback: Generic syntax error detection

Hover Information

Shows symbol information on hover:

  • Source: External LSP servers (primary), configured rules, built-in providers
  • Display: Tooltip on mouse hover
  • Features: Type information, documentation, source location
  • Fallback: Generic symbol lookup

Definition Navigation

Navigate to symbol definitions:

  • Source: External LSP servers (primary), configured rules, built-in providers
  • Trigger: Ctrl+Click or Go to Definition command
  • Features: Jump to definition, peek definition
  • Fallback: Generic pattern-based search

Hot-Reload

Configuration and provider availability changes are detected automatically without restart:

Configuration Hot-Reload

When configuration files change:

  1. Configuration is reloaded
  2. Provider chain is updated
  3. IDE extensions are notified
  4. New configuration takes effect immediately

LSP Server Availability Monitoring

LSP server availability is monitored continuously:

  1. Health checks run periodically (configurable interval)
  2. When LSP becomes available: automatically switch to LSP provider
  3. When LSP becomes unavailable: automatically fall back to next provider
  4. IDE extensions are notified of provider changes

Example: LSP Server Restart

1. LSP server is running and providing completions
2. LSP server crashes
3. Health check detects failure
4. System falls back to configured rules provider
5. User continues working with fallback provider
6. LSP server restarts
7. Health check detects availability
8. System switches back to LSP provider
9. User gets LSP completions again (no restart needed)

Error Handling

Provider Chain Errors

When a provider fails, the system gracefully falls back:

  • External LSP unavailable: Fall back to configured rules (preserve functionality)
  • Configured rules unavailable: Fall back to built-in providers (preserve functionality)
  • Built-in providers unavailable: Fall back to generic features (preserve functionality)
  • All providers unavailable: Return generic error with fallback suggestion

Configuration Errors

Invalid configuration is rejected with clear remediation:

  • Parse errors: Report line number and remediation steps
  • Missing fields: Report missing field with example configuration
  • Invalid values: Report invalid value with list of valid options
  • Path errors: Report path error with remediation (use ricecoder_storage::PathResolver)

IDE Communication Errors

Connection issues are handled gracefully:

  • Connection lost: Attempt reconnect with exponential backoff (max 5 retries)
  • Request timeout: Return timeout error to IDE with configurable timeout
  • Protocol mismatch: Log error and attempt recovery
  • IDE extension disconnected: Clean up resources and prepare for reconnection

Troubleshooting

LSP Server Not Found

Problem: "LSP server not found for language X"

Solutions:

  1. Install the LSP server for your language:
    • Rust: rustup component add rust-analyzer
    • TypeScript: npm install -g typescript-language-server
    • Python: pip install python-lsp-server
  2. Verify the LSP server is in your PATH
  3. Check configuration for correct server command

Completions Not Working

Problem: Code completions are not appearing

Solutions:

  1. Check if LSP server is running: Look for health check logs
  2. Verify IDE extension is installed and enabled
  3. Check configuration for disabled providers
  4. Try manual trigger (Ctrl+Space in VS Code)
  5. Check IDE logs for errors

Configuration Not Applied

Problem: Configuration changes are not taking effect

Solutions:

  1. Verify configuration file syntax (YAML format)
  2. Check configuration file location (see Configuration section)
  3. Verify file permissions (readable by ricecoder)
  4. Check for configuration validation errors in logs
  5. Restart IDE extension if hot-reload doesn't work

IDE Extension Not Connecting

Problem: IDE extension cannot connect to ricecoder

Solutions:

  1. Verify ricecoder is running
  2. Check port configuration (default: 8080 for VS Code)
  3. Verify firewall allows connection
  4. Check IDE extension logs for connection errors
  5. Try restarting IDE extension

Performance Issues

Problem: Completions or diagnostics are slow

Solutions:

  1. Check LSP server health (may be overloaded)
  2. Increase timeout values in configuration
  3. Reduce number of results in configuration
  4. Check system resources (CPU, memory)
  5. Try disabling less-used providers

Performance Characteristics

Completion Latency

  • LSP provider: 50-200ms (depends on LSP server)
  • Configured rules: 10-50ms
  • Built-in providers: 20-100ms
  • Generic fallback: 5-20ms

Diagnostics Latency

  • LSP provider: 100-500ms (depends on file size and LSP server)
  • Configured rules: 20-100ms
  • Built-in providers: 50-200ms
  • Generic fallback: 10-50ms

Memory Usage

  • IDE Integration Manager: ~5-10 MB
  • Provider Registry: ~2-5 MB per language
  • Configuration Cache: ~1-2 MB
  • Total: ~10-30 MB depending on configuration

Limitations

Current Limitations

  • Tier 1 LSP Support Only: Only rust-analyzer, typescript-language-server, and pylsp are officially supported
  • Single LSP Per Language: Only one LSP server per language is supported
  • No LSP Server Implementation: Ricecoder does not implement LSP servers
  • Configuration-Based Customization: Custom behavior requires configuration files

Known Issues

  • Hot-reload may take up to 5 seconds to detect changes
  • Some IDE extensions may not support all features
  • Performance depends on LSP server implementation

See Also

Last updated: December 9, 2025

Clone this wiki locally