LSP 开发指南 / 第 6 章：诊断信息

{
  "jsonrpc": "2.0",
  "method": "textDocument/publishDiagnostics",
  "params": {
    "uri": "file:///home/user/project/src/main.py",
    "version": 5,
    "diagnostics": [
      {
        "range": {
          "start": { "line": 10, "character": 4 },
          "end": { "line": 10, "character": 15 }
        },
        "severity": 1,
        "code": "undefined-variable",
        "source": "pylsp",
        "message": "Undefined variable 'undefined_var'",
        "tags": [],
        "relatedInformation": [
          {
            "location": {
              "uri": "file:///home/user/project/src/utils.py",
              "range": {
                "start": { "line": 5, "character": 0 },
                "end": { "line": 5, "character": 20 }
              }
            },
            "message": "Variable was defined here but removed in latest commit"
          }
        ]
      }
    ]
  }
}

import { DiagnosticSeverity } from "vscode-languageserver";

function createDiagnostic(
  line: number,
  col: number,
  endLine: number,
  endCol: number,
  message: string,
  severity: DiagnosticSeverity,
  code?: string
): Diagnostic {
  return {
    range: {
      start: { line, character: col },
      end: { line: endLine, character: endCol },
    },
    severity,
    source: "my-language-server",
    message,
    code,
  };
}

// 创建不同级别的诊断
const error = createDiagnostic(10, 4, 10, 15, "Undefined variable 'x'", DiagnosticSeverity.Error, "E001");
const warning = createDiagnostic(20, 0, 20, 10, "Unused variable 'temp'", DiagnosticSeverity.Warning, "W001");
const info = createDiagnostic(30, 0, 30, 20, "Consider using list comprehension", DiagnosticSeverity.Information);
const hint = createDiagnostic(40, 0, 40, 15, "Can be simplified to 'return x > 0'", DiagnosticSeverity.Hint);

// 标记未使用的导入
const unnecessaryImport: Diagnostic = {
  range: { start: { line: 0, character: 7 }, end: { line: 0, character: 13 } },
  severity: DiagnosticSeverity.Warning,
  message: "Unused import 'os'",
  source: "my-lsp",
  tags: [DiagnosticTag.Unnecessary],
  code: "unused-import",
};

// 标记已弃用的 API
const deprecatedCall: Diagnostic = {
  range: { start: { line: 15, character: 4 }, end: { line: 15, character: 20 } },
  severity: DiagnosticSeverity.Warning,
  message: "'old_function' is deprecated, use 'new_function' instead",
  source: "my-lsp",
  tags: [DiagnosticTag.Deprecated],
  code: "deprecated-function",
};

const typeMismatch: Diagnostic = {
  range: {
    start: { line: 10, character: 8 },
    end: { line: 10, character: 15 },
  },
  severity: DiagnosticSeverity.Error,
  message: "Type 'string' is not assignable to type 'number'",
  source: "my-lsp",
  relatedInformation: [
    {
      location: {
        uri: "file:///src/types.ts",
        range: {
          start: { line: 42, character: 0 },
          end: { line: 42, character: 30 },
        },
      },
      message: "'count' is declared as number here",
    },
    {
      location: {
        uri: "file:///src/main.ts",
        range: {
          start: { line: 10, character: 8 },
          end: { line: 10, character: 15 },
        },
      },
      message: "The assignment is here",
    },
  ],
};

import { Diagnostic } from "vscode-languageserver";

class DiagnosticProvider {
  private debounceTimer: NodeJS.Timeout | null = null;
  private debounceMs = 300;

  constructor(private connection: any, private docManager: any) {}

  // 文档变更时触发（带防抖）
  scheduleDiagnostics(uri: string): void {
    if (this.debounceTimer) {
      clearTimeout(this.debounceTimer);
    }

    this.debounceTimer = setTimeout(() => {
      this.publishDiagnostics(uri);
    }, this.debounceMs);
  }

  // 立即发布诊断（保存时）
  publishDiagnostics(uri: string): void {
    const doc = this.docManager.get(uri);
    if (!doc) return;

    const diagnostics = this.analyze(doc);

    this.connection.sendNotification("textDocument/publishDiagnostics", {
      uri,
      version: doc.version,
      diagnostics,
    });
  }

  // 清除诊断
  clearDiagnostics(uri: string): void {
    this.connection.sendNotification("textDocument/publishDiagnostics", {
      uri,
      diagnostics: [],
    });
  }

  private analyze(doc: { text: string; uri: string }): Diagnostic[] {
    const diagnostics: Diagnostic[] = [];
    const lines = doc.text.split("\n");

    for (let i = 0; i < lines.length; i++) {
      const line = lines[i];

      // 示例 1：检测未定义变量
      const undefinedMatch = line.match(/\b(undefined_var)\b/);
      if (undefinedMatch) {
        const col = line.indexOf(undefinedMatch[1]);
        diagnostics.push({
          range: {
            start: { line: i, character: col },
            end: { line: i, character: col + undefinedMatch[1].length },
          },
          severity: DiagnosticSeverity.Error,
          source: "my-lsp",
          message: `Undefined variable '${undefinedMatch[1]}'`,
          code: "undefined-variable",
        });
      }

      // 示例 2：检测过长行
      if (line.length > 120) {
        diagnostics.push({
          range: {
            start: { line: i, character: 120 },
            end: { line: i, character: line.length },
          },
          severity: DiagnosticSeverity.Warning,
          source: "my-lsp",
          message: `Line exceeds 120 characters (${line.length})`,
          code: "line-too-long",
        });
      }

      // 示例 3：检测 TODO
      const todoIdx = line.indexOf("TODO");
      if (todoIdx !== -1) {
        diagnostics.push({
          range: {
            start: { line: i, character: todoIdx },
            end: { line: i, character: todoIdx + 4 },
          },
          severity: DiagnosticSeverity.Information,
          source: "my-lsp",
          message: "TODO comment found",
          code: "todo-comment",
          tags: [],
        });
      }
    }

    return diagnostics;
  }
}

const connection = createMessageConnection(/* ... */);
const docManager = new DocumentManager();
const diagnostics = new DiagnosticProvider(connection, docManager);

// 文档打开时分析
connection.onNotification("textDocument/didOpen", (params) => {
  docManager.open(params.textDocument);
  diagnostics.publishDiagnostics(params.textDocument.uri);
});

// 文档变更时防抖分析
connection.onNotification("textDocument/didChange", (params) => {
  // ... 更新文档内容
  diagnostics.scheduleDiagnostics(params.textDocument.uri);
});

// 保存时立即分析
connection.onNotification("textDocument/didSave", (params) => {
  diagnostics.publishDiagnostics(params.textDocument.uri);
});

// 关闭时清除诊断
connection.onNotification("textDocument/didClose", (params) => {
  docManager.close(params.textDocument.uri);
  diagnostics.clearDiagnostics(params.textDocument.uri);
});

class IncrementalDiagnosticProvider {
  private dirtyFiles = new Set<string>();
  private analysisQueue: string[] = [];
  private isAnalyzing = false;

  markDirty(uri: string): void {
    this.dirtyFiles.add(uri);
    this.analysisQueue.push(uri);
    this.processQueue();
  }

  private async processQueue(): Promise<void> {
    if (this.isAnalyzing || this.analysisQueue.length === 0) return;

    this.isAnalyzing = true;

    while (this.analysisQueue.length > 0) {
      const uri = this.analysisQueue.shift()!;
      if (!this.dirtyFiles.has(uri)) continue;

      this.dirtyFiles.delete(uri);
      const diagnostics = await this.analyzeFile(uri);
      this.publishDiagnostics(uri, diagnostics);
    }

    this.isAnalyzing = false;
  }

  private async analyzeFile(uri: string): Promise<Diagnostic[]> {
    // 使用异步分析，避免阻塞
    return new Promise((resolve) => {
      setImmediate(() => {
        const doc = this.docManager.get(uri);
        if (!doc) return resolve([]);
        resolve(this.doAnalyze(doc));
      });
    });
  }
}

{
  "capabilities": {
    "textDocument": {
      "publishDiagnostics": {
        "relatedInformation": true,
        "tagSupport": {
          "valueSet": [1, 2]
        },
        "versionSupport": true,
        "codeDescriptionSupport": true,
        "dataSupport": true
      }
    }
  }
}

// Client 端：过滤特定严重级别的诊断
connection.onNotification("textDocument/publishDiagnostics", (params) => {
  const filteredDiagnostics = params.diagnostics.filter((d) => {
    // 过滤掉 Hint 级别
    if (d.severity === DiagnosticSeverity.Hint) return false;
    // 过滤特定代码
    if (d.code === "todo-comment") return false;
    return true;
  });

  // 更新编辑器 UI
  updateEditorDiagnostics(params.uri, filteredDiagnostics);
});

// Client 主动拉取诊断
connection.onRequest("textDocument/diagnostic", async (params) => {
  const doc = docManager.get(params.textDocument.uri);
  if (!doc) return { items: [] };

  const diagnostics = await analyzeDocument(doc);
  return {
    kind: "full",
    items: diagnostics,
  };
});

// 或者工作区级别拉取
connection.onRequest("workspace/diagnostic", async (params) => {
  const results = [];
  for (const [uri, doc] of docManager.getAllDocuments()) {
    const diagnostics = await analyzeDocument(doc);
    results.push({
      uri,
      version: doc.version,
      diagnostics,
    });
  }
  return { items: results };
});

// diagnostic-codes.ts
export enum DiagnosticCode {
  // Errors
  SyntaxError = "E001",
  TypeError = "E002",
  UndefinedVariable = "E003",
  MissingImport = "E004",
  DuplicateDefinition = "E005",

  // Warnings
  UnusedVariable = "W001",
  UnusedImport = "W002",
  DeprecatedApi = "W003",
  LineTooLong = "W004",
  UnreachableCode = "W005",

  // Info
  TodoComment = "I001",
  Suggestion = "I002",

  // Hints
  SimplifyExpression = "H001",
  AddTypeAnnotation = "H002",
}