LSP 开发指南 / 第 5 章：语言特性

{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "textDocument/completion",
  "params": {
    "textDocument": { "uri": "file:///src/main.py" },
    "position": { "line": 5, "character": 12 },
    "context": {
      "triggerKind": 2,
      "triggerCharacter": "."
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 10,
  "result": {
    "isIncomplete": false,
    "items": [
      {
        "label": "append",
        "kind": 2,
        "detail": "(method) append(object) -> None",
        "documentation": "Append object to the end of the list.",
        "insertText": "append(${1:object})",
        "insertTextFormat": 2,
        "sortText": "0001",
        "filterText": "append",
        "commitCharacters": ["(", ";"]
      }
    ]
  }
}

connection.onRequest("textDocument/completion", (params) => {
  const doc = docManager.get(params.textDocument.uri);
  if (!doc) return { isIncomplete: false, items: [] };

  const line = doc.text.split("\n")[params.position.line];
  const prefix = line.substring(0, params.position.character);

  // 获取当前正在输入的单词
  const wordMatch = prefix.match(/(\w+)$/);
  const word = wordMatch ? wordMatch[1] : "";

  // 触发字符上下文
  const triggerChar = params.context?.triggerCharacter;
  let items: CompletionItem[] = [];

  if (triggerChar === ".") {
    // 对象成员补全
    items = getMemberCompletions(doc, params.position);
  } else if (triggerChar === ":") {
    // 类型注解补全
    items = getTypeCompletions(doc, params.position);
  } else {
    // 通用补全
    items = [
      ...getLocalSymbols(doc, params.position),
      ...getBuiltinSymbols(),
    ];
  }

  // 根据输入前缀过滤
  if (word) {
    items = items.filter((item) =>
      item.label.toLowerCase().startsWith(word.toLowerCase())
    );
  }

  return {
    isIncomplete: false,
    items,
  };
});

// 补全项解析（惰性加载详情）
connection.onRequest("completionItem/resolve", (item) => {
  // 只有用户选中某项后才加载完整文档
  if (!item.documentation) {
    item.documentation = loadFullDocumentation(item.label);
  }
  return item;
});

// Python def 模板
const snippet: CompletionItem = {
  label: "def",
  kind: CompletionItemKind.Snippet,
  detail: "Define a function",
  insertText: "def ${1:function_name}(${2:params}):\n    \"\"\"${3:Docstring}\"\"\"\n    $0",
  insertTextFormat: InsertTextFormat.Snippet,
  documentation: {
    kind: MarkupKind.Markdown,
    value: "```python\ndef function_name(params):\n    \"\"\"Docstring\"\"\"\n    pass\n```",
  },
};

{
  "jsonrpc": "2.0",
  "id": 11,
  "method": "textDocument/hover",
  "params": {
    "textDocument": { "uri": "file:///src/main.py" },
    "position": { "line": 5, "character": 8 }
  }
}

{
  "jsonrpc": "2.0",
  "id": 11,
  "result": {
    "contents": {
      "kind": "markdown",
      "value": "```python\ndef calculate_sum(a: int, b: int) -> int\n```\n\n---\n\nCalculate the sum of two integers.\n\n**Parameters:**\n- `a` - First integer\n- `b` - Second integer\n\n**Returns:** The sum of a and b"
    },
    "range": {
      "start": { "line": 5, "character": 4 },
      "end": { "line": 5, "character": 17 }
    }
  }
}

connection.onRequest("textDocument/hover", (params) => {
  const doc = docManager.get(params.textDocument.uri);
  if (!doc) return null;

  const symbol = findSymbolAtPosition(doc, params.position);
  if (!symbol) return null;

  // 构建 Markdown 悬停内容
  let markdown = "";

  if (symbol.kind === "function") {
    markdown = buildFunctionHover(symbol);
  } else if (symbol.kind === "variable") {
    markdown = buildVariableHover(symbol);
  } else if (symbol.kind === "class") {
    markdown = buildClassHover(symbol);
  }

  if (!markdown) return null;

  return {
    contents: {
      kind: "markdown",
      value: markdown,
    },
    range: symbol.range,
  };
});

function buildFunctionHover(fn: SymbolInfo): string {
  const signature = `\`\`\`python\ndef ${fn.name}(${fn.parameters
    .map((p) => `${p.name}: ${p.type}`)
    .join(", ")}) -> ${fn.returnType}\n\`\`\``;

  const description = fn.documentation
    ? `\n---\n\n${fn.documentation}`
    : "";

  return signature + description;
}

{
  "jsonrpc": "2.0",
  "id": 12,
  "method": "textDocument/definition",
  "params": {
    "textDocument": { "uri": "file:///src/main.py" },
    "position": { "line": 10, "character": 4 }
  }
}

{
  "jsonrpc": "2.0",
  "id": 12,
  "result": [
    {
      "uri": "file:///src/utils.py",
      "range": {
        "start": { "line": 24, "character": 0 },
        "end": { "line": 24, "character": 30 }
      }
    }
  ]
}

connection.onRequest("textDocument/definition", (params) => {
  const doc = docManager.get(params.textDocument.uri);
  if (!doc) return null;

  const word = getWordAtPosition(doc.text, params.position);
  if (!word) return null;

  // 在所有文档中查找定义
  const definitions: Location[] = [];

  for (const [uri, otherDoc] of docManager.getAllDocuments()) {
    const def = findDefinition(otherDoc, word);
    if (def) {
      definitions.push({ uri, range: def.range });
    }
  }

  // 如果在同一文件中有引用，排除自身位置
  return definitions.filter((loc) => {
    if (loc.uri !== params.textDocument.uri) return true;
    const pos = params.position;
    const start = loc.range.start;
    const end = loc.range.end;
    return !(pos.line === start.line && pos.character >= start.character && pos.character <= end.character);
  });
});

function findDefinition(doc: TextDocumentItem, word: string): { range: Range } | null {
  const lines = doc.text.split("\n");
  for (let i = 0; i < lines.length; i++) {
    // 简单匹配：查找 def/class/var 定义
    const patterns = [
      new RegExp(`^(def|function)\\s+${word}\\b`),
      new RegExp(`^(class|interface)\\s+${word}\\b`),
      new RegExp(`^${word}\\s*[=:]`),
    ];

    for (const pattern of patterns) {
      if (pattern.test(lines[i])) {
        const charStart = lines[i].indexOf(word);
        return {
          range: {
            start: { line: i, character: charStart },
            end: { line: i, character: charStart + word.length },
          },
        };
      }
    }
  }
  return null;
}

{
  "jsonrpc": "2.0",
  "id": 13,
  "method": "textDocument/references",
  "params": {
    "textDocument": { "uri": "file:///src/main.py" },
    "position": { "line": 5, "character": 4 },
    "context": {
      "includeDeclaration": true
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 13,
  "result": [
    {
      "uri": "file:///src/main.py",
      "range": {
        "start": { "line": 5, "character": 4 },
        "end": { "line": 5, "character": 15 }
      }
    },
    {
      "uri": "file:///src/main.py",
      "range": {
        "start": { "line": 20, "character": 8 },
        "end": { "line": 20, "character": 19 }
      }
    },
    {
      "uri": "file:///src/utils.py",
      "range": {
        "start": { "line": 42, "character": 12 },
        "end": { "line": 42, "character": 23 }
      }
    }
  ]
}

connection.onRequest("textDocument/references", (params) => {
  const doc = docManager.get(params.textDocument.uri);
  if (!doc) return [];

  const word = getWordAtPosition(doc.text, params.position);
  if (!word) return [];

  const references: Location[] = [];

  // 在所有已打开的文档中搜索
  for (const [uri, otherDoc] of docManager.getAllDocuments()) {
    const lines = otherDoc.text.split("\n");
    for (let lineIdx = 0; lineIdx < lines.length; lineIdx++) {
      let colIdx = 0;
      const lineText = lines[lineIdx];

      while (colIdx < lineText.length) {
        const matchIdx = lineText.indexOf(word, colIdx);
        if (matchIdx === -1) break;

        // 验证是完整单词匹配
        const before = matchIdx > 0 ? lineText[matchIdx - 1] : " ";
        const after = matchIdx + word.length < lineText.length
          ? lineText[matchIdx + word.length]
          : " ";

        if (/\w/.test(before) || /\w/.test(after)) {
          colIdx = matchIdx + 1;
          continue;
        }

        references.push({
          uri,
          range: {
            start: { line: lineIdx, character: matchIdx },
            end: { line: lineIdx, character: matchIdx + word.length },
          },
        });

        colIdx = matchIdx + word.length;
      }
    }
  }

  return references;
});

{
  "jsonrpc": "2.0",
  "id": 14,
  "method": "textDocument/signatureHelp",
  "params": {
    "textDocument": { "uri": "file:///src/main.py" },
    "position": { "line": 10, "character": 25 },
    "context": {
      "triggerKind": 2,
      "triggerCharacter": ",",
      "isRetrigger": false
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 14,
  "result": {
    "signatures": [
      {
        "label": "calculate(a: int, b: int, c: int) -> int",
        "documentation": "Perform a three-way calculation",
        "parameters": [
          {
            "label": [10, 22],
            "documentation": "First parameter"
          },
          {
            "label": [24, 36],
            "documentation": "Second parameter"
          },
          {
            "label": [38, 50],
            "documentation": "Third parameter"
          }
        ],
        "activeParameter": 1
      }
    ],
    "activeSignature": 0,
    "activeParameter": 1
  }
}

connection.onRequest("textDocument/signatureHelp", (params) => {
  const doc = docManager.get(params.textDocument.uri);
  if (!doc) return null;

  const { line, character } = params.position;
  const lines = doc.text.split("\n");
  const lineText = lines[line];

  // 从光标位置向前搜索函数调用
  const funcInfo = findEnclosingFunctionCall(lineText, character);
  if (!funcInfo) return null;

  // 查找函数定义
  const funcDef = findFunctionDefinition(doc, funcInfo.name);
  if (!funcDef) return null;

  const signatureLabel = buildSignatureLabel(funcDef);

  return {
    signatures: [
      {
        label: signatureLabel,
        documentation: funcDef.documentation ?? "",
        parameters: funcDef.parameters.map((p) => ({
          label: `${p.name}: ${p.type}`,
          documentation: p.documentation ?? "",
        })),
      },
    ],
    activeSignature: 0,
    activeParameter: funcInfo.currentParamIndex,
  };
});

interface FuncCallInfo {
  name: string;
  currentParamIndex: number;
}

function findEnclosingFunctionCall(lineText: string, cursorPos: number): FuncCallInfo | null {
  let depth = 0;
  let paramIndex = 0;

  // 从光标位置向后回溯
  for (let i = cursorPos - 1; i >= 0; i--) {
    const ch = lineText[i];
    if (ch === ")") {
      depth++;
    } else if (ch === "(") {
      if (depth === 0) {
        // 找到了对应的左括号
        const beforeParen = lineText.substring(0, i).trim();
        const funcMatch = beforeParen.match(/(\w+)\s*$/);
        if (funcMatch) {
          return { name: funcMatch[1], currentParamIndex: paramIndex };
        }
        return null;
      }
      depth--;
    } else if (ch === "," && depth === 0) {
      paramIndex++;
    }
  }

  return null;
}

{
  "capabilities": {
    "signatureHelpProvider": {
      "triggerCharacters": ["(", ",", ")"],
      "retriggerCharacters": ["."]
    }
  }
}

// 请求类型层次
connection.onRequest("typeHierarchy/supertypes", async (params) => {
  const className = findClassAtPosition(params.item);
  if (!className) return [];

  const superClass = findSuperClass(className);
  return superClass
    ? [{ name: superClass.name, kind: SymbolKind.Class, uri: superClass.uri, range: superClass.range }]
    : [];
});

connection.onRequest("typeHierarchy/subtypes", async (params) => {
  const className = findClassAtPosition(params.item);
  if (!className) return [];

  return findSubClasses(className).map((sub) => ({
    name: sub.name,
    kind: SymbolKind.Class,
    uri: sub.uri,
    range: sub.range,
  }));
});