Deno LSP 中 Hover 功能的 JSON 响应格式问题分析

在 Deno 语言服务器协议（LSP）实现中，textDocument/hover 请求返回的 JSON 响应格式存在一个技术规范遵循问题。该问题涉及 LSP 3.17 规范中对 Hover 响应内容类型的定义变更。

问题背景

Deno LSP 在处理代码悬停提示（hover）请求时，返回的 JSON 响应中使用了已被废弃的 MarkedString 格式。根据 LSP 3.17 规范，这种格式已被标记为废弃，推荐使用更现代的 MarkupContent 格式替代。

技术规范对比

LSP 规范定义了三种可能的 Hover 响应内容格式：

1. MarkedString（已废弃）：

   • 可以是纯字符串
   • 或是包含 language 和 value 字段的对象
   • 主要用于渲染人类可读文本

2. MarkedString[]（已废弃）：

   • MarkedString 的数组形式

3. MarkupContent（推荐）：

   • 包含 kind 和 value 字段
   • kind 可以是 'plaintext' 或 'markdown'
   • 提供更结构化的内容表示方式

具体问题表现

Deno LSP 当前返回的响应示例显示，它仍然在使用 MarkedString[] 格式：

{
  "contents": [
    {"language":"typescript","value":"(method) Console.log(...data: any[]): void"},
    "Outputs a message to the console",
    "\n\n*@param* - data Values to be printed to the console  \n\n*@example*  \n```ts\nconsole.log('Hello', 'World', 123);\n```"
  ],
  "range": {...}
}

而根据规范，理想的响应应该采用 MarkupContent 格式，如 Go 语言的 gopls 实现所示：

{
  "contents": {
    "kind": "markdown",
    "value": "```go\nfunc fmt.Sprintf(format string, a ...any) string\n```\n\n---\n\nSprintf formats according to a format specifier and returns the resulting string.\n\n\n---\n\n[`fmt.Sprintf` on pkg.go.dev](https://pkg.go.dev/fmt#Sprintf)"
  },
  "range": {...}
}

影响分析

虽然使用废弃格式在功能上可能不会立即出现问题，但会带来以下潜在影响：

1. 兼容性问题：未来 LSP 客户端可能逐步移除对废弃格式的支持
2. 功能限制：MarkedString 格式无法充分利用 Markdown 的全部特性
3. 维护成本：需要后续进行技术债务清理

解决方案建议

建议 Deno LSP 实现进行以下改进：

1. 将 Hover 响应统一转换为 MarkupContent 格式
2. 使用 markdown 作为内容类型，以支持更丰富的格式
3. 将代码片段、描述文本和参数文档整合为单一的 Markdown 字符串

这种改进将使 Deno LSP 更符合现代 LSP 实现的最佳实践，提高与其他工具的兼容性，并为未来功能扩展奠定更好的基础。