fix(cpp): explain missing clang-tidy checks with Apple's clangd (#770)

Apple's clangd (/usr/bin/clangd, Xcode and CommandLineTools toolchains) is built without clang-tidy, so on a Mac without a managed clangd the checks from .clang-tidy never appear. When a clangd server for C, C++, Objective-C or Objective-C++ resolves to Apple's binary and the project has a .clang-tidy, show one warning per session with Install (managed LLVM clangd, which already takes precedence once installed) and Language Servers… actions. Fixes #692.

src/bindings.ts

@@ -3619,6 +3619,8 @@ cancellable: boolean } |
 { type: "indexState"; indexing: boolean; files: number; symbols: number } | 
 /**  Git status / branch information should be refreshed. */
 { type: "vcsChanged"; root: IpcPath } | { type: "languageServer"; server: ServerId; name: string; status: ServerStatus; message: string | null } | 
+/**  A running server lacks a capability; the UI offers the managed tool as a replacement. */
+{ type: "languageServerWarning"; name: string; message: string; installTool: string } | 
 /**
  *  A stopped language server left the project's list (disabled in settings, or a
  *  fallback that a preferred server took over from again).

src/features/tools/__tests__/tools.test.tsx

@@ -7,7 +7,7 @@ import { useTasks } from "@/workbench/tasks";
 import { MemoryToolsBackend, sampleTools, setToolsBackend } from "../backend";
 import { cancelInstall, installTool, refreshTools, uninstallTool, useTools } from "../store";
 import { filterTools, LanguageServersPage } from "../LanguageServersPage";
-import { installMissingServerPrompts, missingKey, promptInstall } from "../missing";
+import { installMissingServerPrompts, installServerWarningPrompts, missingKey, promptInstall } from "../missing";
 import { resetTestForm, stagedFor, TestSettingsForm } from "./settingsForm";
 
 type Note = Parameters<NotificationService["notify"]>[0];
@@ -273,3 +273,49 @@ describe("tools.install action", () => {
     }
   });
 });
+
+describe("language server capability warning", () => {
+  const event = {
+    type: "languageServerWarning",
+    name: "clangd",
+    message:
+      "Apple's clangd does not run clang-tidy, so checks from .clang-tidy are not shown. Install clangd (LLVM) to get them.",
+    installTool: "clangd",
+  } as const;
+
+  it("offers a managed replacement for system clangd once and restarts it after installation", async () => {
+    backend.tools.push({
+      ...sampleTools()[0]!,
+      name: "clangd",
+      displayName: "clangd",
+      command: "clangd",
+      status: "onPath",
+      path: "/usr/bin/clangd",
+      languages: ["C", "C++", "Objective-C", "Objective-C++"],
+    });
+    const off = installServerWarningPrompts();
+    try {
+      emitLocalIdeEvent(event);
+      emitLocalIdeEvent(event);
+      await waitFor(() => expect(notes).toHaveLength(1));
+      expect(notes[0]).toMatchObject({ title: "clangd", level: "warning", sticky: true, body: event.message });
+      expect(notes[0]!.actions!.map((a) => a.label)).toEqual(["Install", "Language Servers…"]);
+      notes[0]!.actions![0]!.run();
+      await waitFor(() => expect(backend.restarted).toEqual(["clangd"]));
+      expect(notes.at(-1)).toMatchObject({ title: "clangd installed", key: notes[0]!.key });
+    } finally {
+      off();
+    }
+  });
+
+  it("keeps the Settings action when the tool cannot be installed", async () => {
+    const off = installServerWarningPrompts();
+    try {
+      emitLocalIdeEvent(event);
+      await waitFor(() => expect(notes).toHaveLength(1));
+      expect(notes[0]!.actions!.map((a) => a.label)).toEqual(["Language Servers…"]);
+    } finally {
+      off();
+    }
+  });
+});

src/features/tools/index.ts

@@ -9,7 +9,7 @@ import { lazyComponent } from "@/ui";
 import { executeAction, registerActions } from "@/platform/actions";
 import { registerSettingsPage } from "@/workbench/contributions";
 import { installJdkPrompts, registerJdkActions } from "./jdk";
-import { installMissingServerPrompts, promptInstall } from "./missing";
+import { installMissingServerPrompts, installServerWarningPrompts, promptInstall } from "./missing";
 import { installTool, refreshTools, SETTINGS_PAGE_ID, toolByName, useTools } from "./store";
 
 /** The Language Servers page (also used by the Settings window). */
@@ -79,6 +79,7 @@ export function activate(): () => void {
       },
     ]),
     installMissingServerPrompts(),
+    installServerWarningPrompts(),
     registerJdkActions(),
     installJdkPrompts(),
   ];

src/features/tools/missing.ts

@@ -56,3 +56,31 @@ export function installMissingServerPrompts(): () => void {
     void promptInstall(e.name).catch(() => {});
   });
 }
+
+/** A system server that lacks a capability can be replaced by the managed tool. */
+export function installServerWarningPrompts(): () => void {
+  const prompted = new Set<string>();
+  return onIdeEvent("languageServerWarning", (e) => {
+    const key = `lsp-warning-${e.name}-${e.installTool}`;
+    if (prompted.has(key)) return;
+    prompted.add(key);
+    void (async () => {
+      if (!useTools.getState().loaded) await refreshTools();
+      const tool = toolByName(e.installTool);
+      notifications().notify({
+        group: "lsp",
+        level: "warning",
+        title: e.name,
+        body: tx(e.message),
+        key,
+        sticky: true,
+        actions: [
+          ...(tool?.canInstall
+            ? [{ label: "Install", run: () => void installTool(e.installTool, { notificationKey: key }) }]
+            : []),
+          { label: "Language Servers…", run: () => void executeAction("file.settings", SETTINGS_PAGE_ID) },
+        ],
+      });
+    })();
+  });
+}

src/platform/locales/text/zh.json

@@ -1,4 +1,5 @@
 {
+  "Apple's clangd does not run clang-tidy, so checks from .clang-tidy are not shown. Install clangd (LLVM) to get them.": "Apple 的 clangd 不运行 clang-tidy，因此不会显示 .clang-tidy 中配置的检查。请安装 clangd（LLVM）以启用这些检查。",
   "Newer dependency version available": "有更新的依赖版本可用",
   "Reports newer crate versions that Cargo.toml requirements do not already allow.": "报告 Cargo.toml 版本要求尚未允许的较新 crate 版本。",
   "Update to {latest}": "更新至 {latest}",