[Story] LSP Phase 4: Hover with rule explanations

[ekropotin]

User Story

As a developer seeing a linting error, I want to hover over the diagnostic to see detailed rule explanation and examples, so I understand how to fix the issue.

Acceptance Criteria

• Hover requests return formatted rule documentation for violations
• Includes rule description, rationale, and fix examples
• Works for all implemented rules
• Hover works on both the diagnostic squiggly lines and rule codes
• Graceful fallback for rules without detailed documentation
• Performance optimized - no re-linting on hover

Additional Context

Technical Implementation Details:

LSP Capability Registration:

{
  "capabilities": {
    "hoverProvider": true
  }
}

Hover Request Handling:

• textDocument/hover → Query cached diagnostics at position, return rule documentation

Rule Documentation Structure:

pub struct RuleDocumentation {
    pub code: &'static str,           // "MD013"
    pub name: &'static str,           // "Line length"
    pub description: &'static str,    // Brief explanation
    pub rationale: &'static str,      // Why this rule exists
    pub examples: RuleExamples,       // Good/bad examples
    pub configuration: Option<RuleConfig>, // Available settings
}

pub struct RuleExamples {
    pub incorrect: Vec<&'static str>, // Examples that violate the rule
    pub correct: Vec<&'static str>,   // Examples that follow the rule
}

pub struct RuleConfig {
    pub settings: Vec<ConfigSetting>,
    pub default_values: serde_json::Value,
}

Documentation Storage Strategy:

// Static documentation registry - no runtime overhead
pub static RULE_DOCS: &[RuleDocumentation] = &[
    RuleDocumentation {
        code: "MD013",
        name: "Line length",
        description: "Line length should not exceed the configured limit",
        rationale: "Long lines are harder to read and may not display properly on all devices",
        examples: RuleExamples {
            incorrect: &[
                "This is a very long line that exceeds the configured character limit and should be wrapped"
            ],
            correct: &[
                "This is a properly wrapped line that stays\nwithin the configured character limit"
            ]
        },
        configuration: Some(RuleConfig {
            settings: vec\![
                ConfigSetting {
                    name: "line_length",
                    description: "Maximum line length",
                    type_info: "integer",
                    default: "80"
                }
            ]
        })
    },
    // ... other rules
];

Hover Content Format (Markdown):

## MD013 - Line length

Line length should not exceed the configured limit

**Rationale:** Long lines are harder to read and may not display properly on all devices

### Configuration
- `line_length`: Maximum line length (default: 80)

### Examples

❌ **Incorrect:**
```markdown
This is a very long line that exceeds the configured character limit and should be wrapped

✅ Correct:

This is a properly wrapped line that stays
within the configured character limit

Current Violation

Line exceeds limit: 95/80 characters

**Performance Considerations**:
- Use cached diagnostic results from previous linting
- Static rule documentation - no file I/O on hover
- Fast position-based diagnostic lookup using spatial data structures
- Debounce hover requests to prevent spam

**Integration with Existing Rules**:
- Extend `Rule` struct to include documentation metadata
- Update all existing rules to provide documentation
- Fallback to basic info for rules without full documentation

This is Phase 4 of a 6-phase LSP implementation plan for QuickMark.