diff --git a/Extension/src/LanguageServer/Providers/codeActionProvider.ts b/Extension/src/LanguageServer/Providers/codeActionProvider.ts index 858215cb1..bb81a363a 100644 --- a/Extension/src/LanguageServer/Providers/codeActionProvider.ts +++ b/Extension/src/LanguageServer/Providers/codeActionProvider.ts @@ -122,6 +122,7 @@ export class CodeActionProvider implements vscode.CodeActionProvider { const disableCodeActions: vscode.CodeAction[] = []; const removeCodeActions: vscode.CodeAction[] = []; const docCodeActions: vscode.CodeAction[] = []; + const docTargets: Set = new Set(); const showClear: string = new CppSettings().clangTidyCodeActionShowClear; // Check which code actions to show. This can get called a lot @@ -174,10 +175,16 @@ export class CodeActionProvider implements vscode.CodeActionProvider { } } - if (codeActionCodeInfo === undefined || codeActionCodeInfo.docCodeAction === undefined) { + if (codeAction.docCodeAction === undefined) { continue; } - docCodeActions.push(codeActionCodeInfo.docCodeAction); + // Same check code can show up for several folders, and the target depends on + // the clang-tidy release each folder runs, so keep the URLs distinct. + const docTarget: string | undefined = codeAction.docCodeAction.command?.arguments?.[0]?.toString(); + if (docTarget !== undefined && !docTargets.has(docTarget)) { + docTargets.add(docTarget); + docCodeActions.push(codeAction.docCodeAction); + } } if (fixCodeActions.length > 0) { resultCodeActions.push(...fixCodeActions); diff --git a/Extension/src/LanguageServer/clangTidyDocumentation.ts b/Extension/src/LanguageServer/clangTidyDocumentation.ts new file mode 100644 index 000000000..0f7fa1fc6 --- /dev/null +++ b/Extension/src/LanguageServer/clangTidyDocumentation.ts @@ -0,0 +1,44 @@ +/* -------------------------------------------------------------------------------------------- + * Copyright (c) Microsoft Corporation. All Rights Reserved. + * See 'LICENSE' in the project root for license information. + * ------------------------------------------------------------------------------------------ */ + +/** + * The clang-tidy documentation is published per major LLVM release, so a check's page lives + * under the .1.0 release of the major the binary in use comes from: 23.1.0 and 22.1.0 have + * pages, 23.1.1 and 22.1.3 do not. Checks added in a newer major have no page in an older one, + * so the URL follows the binary in use rather than the release bundled with the extension. + * When the version in use could not be determined, fall back to the bundled release. + */ +const versionPattern: RegExp = /^([0-9]+)\.[0-9]+\.[0-9]+$/; + +/** + * The version token `clang-tidy --version` reports, exactly as written. + * + * A release prints a plain X.Y.Z, but a development build prints a suffix (24.0.0git) and a + * prerelease prints one too (19.1.0-rc1). The suffix is kept so that documentationRelease can + * reject those: the .1.0 page for their major is not published until that release exists, so + * building a URL from the stripped number points at a 404. + */ +export function clangTidyVersionFromOutput(output: string): string | undefined { + return output.match(/(\d+\.\d+\.\d+\S*)/)?.[1]; +} + +/** The release a clang-tidy version's documentation was published under. */ +function documentationRelease(clangTidyVersion: string): string | undefined { + const match: RegExpMatchArray | null = clangTidyVersion.match(versionPattern); + return match ? `${match[1]}.1.0` : undefined; +} + +/** + * The clang-tidy release bundled with the extension. Its documentation is published under the + * .1.0 release of its major, so the fallback follows this rather than spelling out a URL version. + */ +export const bundledClangTidyVersion: string = '23.1.1'; + +export const fallbackClangTidyDocVersion: string = documentationRelease(bundledClangTidyVersion) ?? '23.1.0'; + +export function getClangTidyDocumentationUrl(docPage: string, clangTidyVersion?: string): string { + const release: string | undefined = clangTidyVersion ? documentationRelease(clangTidyVersion) : undefined; + return `https://releases.llvm.org/${release ?? fallbackClangTidyDocVersion}/tools/clang/tools/extra/docs/clang-tidy/${docPage}`; +} diff --git a/Extension/src/LanguageServer/codeAnalysis.ts b/Extension/src/LanguageServer/codeAnalysis.ts index 61cc8cf06..86bf36895 100644 --- a/Extension/src/LanguageServer/codeAnalysis.ts +++ b/Extension/src/LanguageServer/codeAnalysis.ts @@ -6,6 +6,7 @@ import * as vscode from 'vscode'; import { NotificationType, Range } from 'vscode-languageclient'; import * as nls from 'vscode-nls'; +import { getClangTidyDocumentationUrl } from './clangTidyDocumentation'; import { Location, WorkspaceEdit } from './commonTypes'; import { CppSourceStr } from './extension'; import { LanguageClient } from './languageClient'; @@ -34,6 +35,7 @@ export interface CodeActionDiagnosticInfo { fixCodeAction?: vscode.CodeAction; // suppressCodeAction?: vscode.CodeAction; // TODO? removeCodeAction?: vscode.CodeAction; + docCodeAction?: vscode.CodeAction; } // Used to handle fix invalidation after an edit, @@ -63,7 +65,6 @@ export interface CodeActionCodeInfo { fixAllTypeCodeAction?: vscode.CodeAction; disableAllTypeCodeAction?: vscode.CodeAction; removeAllTypeCodeAction?: vscode.CodeAction; - docCodeAction?: vscode.CodeAction; } interface CodeActionAllInfo { @@ -256,6 +257,11 @@ export function publishCodeAnalysisDiagnostics(params: PublishCodeAnalysisDiagno } ++nextVersion; const codeActionDiagnosticInfo: CodeActionDiagnosticInfo[] = []; + // The clang-tidy version depends on the resource and on the workspace folders, not on the + // diagnostic, so resolve it once for the file instead of once per diagnostic code. + const clangTidySettings: CppSettings = new CppSettings(realUri); + const clangTidyVersion: string | undefined = clangTidySettings.clangTidyVersion; + const showDocumentation: boolean = clangTidySettings.clangTidyCodeActionShowDocumentation; for (const d of params.diagnostics) { const diagnostic: vscode.Diagnostic = new vscode.Diagnostic(makeVscodeRange(d.range), getLocalizedString(d.localizeStringParams), d.severity); @@ -379,24 +385,22 @@ export function publishCodeAnalysisDiagnostics(params: PublishCodeAnalysisDiagno const checksPage: string = dashIndex > 0 ? primaryCode.substring(dashIndex + 1) : primaryCode; docPage = `checks${checksGroup}/${checksPage}.html`; } - // TODO: This should be checking the clang-tidy version used to better support usage of older versions. - const primaryDocUri: vscode.Uri = vscode.Uri.parse(`https://releases.llvm.org/23.1.0/tools/clang/tools/extra/docs/clang-tidy/${docPage}`); + const primaryDocUri: vscode.Uri = vscode.Uri.parse(getClangTidyDocumentationUrl(docPage, clangTidyVersion)); diagnostic.code = { value: identifier.code, target: primaryDocUri }; - if (new CppSettings().clangTidyCodeActionShowDocumentation) { - if (codeActionCodeInfo.docCodeAction === undefined) { - codeActionCodeInfo.docCodeAction = { - title: localize("show.documentation.for", "Show documentation for {0}", primaryCode), - command: { - title: 'ShowDocumentation', - command: 'C_Cpp.ShowCodeAnalysisDocumentation', - arguments: [primaryDocUri] - }, - kind: vscode.CodeActionKind.QuickFix - }; - } - } else { - codeActionCodeInfo.docCodeAction = undefined; + // The target URL follows the clang-tidy version in use for this resource, so the + // action belongs to the diagnostic. Caching it per check code instead would keep + // whichever folder reported first and reuse its release everywhere. + if (showDocumentation) { + codeAction.docCodeAction = { + title: localize("show.documentation.for", "Show documentation for {0}", primaryCode), + command: { + title: 'ShowDocumentation', + command: 'C_Cpp.ShowCodeAnalysisDocumentation', + arguments: [primaryDocUri] + }, + kind: vscode.CodeActionKind.QuickFix + }; } } else { diagnostic.code = d.code; diff --git a/Extension/src/LanguageServer/settings.ts b/Extension/src/LanguageServer/settings.ts index 499431d09..3003b9ebf 100644 --- a/Extension/src/LanguageServer/settings.ts +++ b/Extension/src/LanguageServer/settings.ts @@ -12,10 +12,11 @@ import * as vscode from 'vscode'; import * as nls from 'vscode-nls'; import * as which from 'which'; import * as util from '../common'; -import { getCachedClangFormatPath, getCachedClangTidyPath, getExtensionFilePath, getRawSetting, isArray, isArrayOfString, isBoolean, isNumber, isObject, isString, isValidMapping, setCachedClangFormatPath, setCachedClangTidyPath } from '../common'; +import { getCachedClangFormatPath, getCachedClangTidyPath, getCachedClangTidyVersion, getExtensionFilePath, getRawSetting, isArray, isArrayOfString, isBoolean, isNumber, isObject, isString, isValidMapping, setCachedClangFormatPath, setCachedClangTidyPath, setCachedClangTidyVersion } from '../common'; import { isWindows } from '../constants'; import * as telemetry from '../telemetry'; import { cachedEditorConfigLookups, DefaultClient, hasTrustedCompilerPaths } from './client'; +import { clangTidyVersionFromOutput } from './clangTidyDocumentation'; import { getEditorConfigSettings, mapIndentationReferenceToEditorConfig, mapIndentToEditorConfig, mapNewOrSameLineToEditorConfig, mapWrapToEditorConfig } from './editorConfig'; import { clients } from './extension'; import { CommentPattern } from './languageConfig'; @@ -279,6 +280,34 @@ export class CppSettings extends Settings { return this.getClangPath(false); } + public get clangTidyVersion(): string | undefined { + // The cached version comes from an auto-discovered binary, so it says nothing about the + // clang-tidy a resource carrying its own path is running. Reporting it would point that + // resource's documentation links at the wrong release, so leave the version unknown and + // let the caller fall back. + if (changeBlankStringToUndefined(this.getAsStringOrUndefined("codeAnalysis.clangTidy.path"))) { + return undefined; + } + // A multi-root workspace can mix that: one folder sets an explicit path, another relies on + // auto-discovery, and a translation unit from the first can report a header that lives in + // the second. The diagnostic only carries the file's URI, so the folder of that URI does + // not say which clang-tidy ran. As soon as any folder overrides the path, the cached + // auto-discovered version is not trustworthy and the caller has to fall back. + if (this.anyWorkspaceFolderOverridesClangTidyPath()) { + return undefined; + } + return getCachedClangTidyVersion(); + } + + private anyWorkspaceFolderOverridesClangTidyPath(): boolean { + const folders: readonly vscode.WorkspaceFolder[] | undefined = vscode.workspace.workspaceFolders; + if (folders === undefined || folders.length === 0) { + return false; + } + return folders.some((folder: vscode.WorkspaceFolder) => + changeBlankStringToUndefined(new CppSettings(folder.uri).getAsStringOrUndefined("codeAnalysis.clangTidy.path")) !== undefined); + } + public get clangFormatPath(): string | undefined { return this.getClangPath(true); } @@ -303,6 +332,7 @@ export class CppSettings extends Settings { } else { // Attempt to invoke both our own version of clang-* to see if we can successfully execute it, and to get its version. let bundledVersion: string; + let clangVersion: string | undefined; try { const bundledPath: string = getExtensionFilePath(`./LLVM/bin/${clangName}`); const output: string = execFileSync(bundledPath, ['--version']).toString(); @@ -318,14 +348,25 @@ export class CppSettings extends Settings { // Invoke the version on the system to compare versions. Use ours if it's more recent. try { const output: string = execFileSync(path, ['--version']).toString(); - const userVersion = output.match(/(\d+\.\d+\.\d+)/)?.[1] ?? ""; - if (semver.ltr(userVersion, bundledVersion)) { + const userVersion: string = clangTidyVersionFromOutput(output) ?? ""; + // Compare on the plain number: semver rejects 24.0.0git. The cache keeps the + // token as written, so a development build is not mistaken for a release. + const userRelease: string = userVersion.match(/(\d+\.\d+\.\d+)/)?.[1] ?? ""; + if (semver.ltr(userRelease, bundledVersion)) { path = ""; setCachedClangPath(path); + clangVersion = bundledVersion; + } else { + clangVersion = userVersion; } } catch { path = ""; setCachedClangPath(path); + clangVersion = bundledVersion; + } + + if (!isFormat && clangVersion) { + setCachedClangTidyVersion(clangVersion); } } } diff --git a/Extension/src/common.ts b/Extension/src/common.ts index 700d8ab44..1022d2b8c 100644 --- a/Extension/src/common.ts +++ b/Extension/src/common.ts @@ -60,6 +60,15 @@ export function setCachedClangTidyPath(path: string): void { cachedClangTidyPath = path; } +let cachedClangTidyVersion: string | undefined; +export function getCachedClangTidyVersion(): string | undefined { + return cachedClangTidyVersion; +} + +export function setCachedClangTidyVersion(version: string): void { + cachedClangTidyVersion = version; +} + // Use this package.json to read values export const packageJson: any = vscode.extensions.getExtension("ms-vscode.cpptools")?.packageJSON; diff --git a/Extension/test/unit/clangTidyDocumentation.test.ts b/Extension/test/unit/clangTidyDocumentation.test.ts new file mode 100644 index 000000000..09158644b --- /dev/null +++ b/Extension/test/unit/clangTidyDocumentation.test.ts @@ -0,0 +1,60 @@ +/* -------------------------------------------------------------------------------------------- + * Copyright (c) Microsoft Corporation. All Rights Reserved. + * See 'LICENSE' in the project root for license information. + * ------------------------------------------------------------------------------------------ */ + +import { describe, it } from 'mocha'; +import { strictEqual } from 'node:assert'; +import { bundledClangTidyVersion, clangTidyVersionFromOutput, fallbackClangTidyDocVersion, getClangTidyDocumentationUrl } from '../../src/LanguageServer/clangTidyDocumentation'; + +const bundledDocUrl: string = `https://releases.llvm.org/${fallbackClangTidyDocVersion}/tools/clang/tools/extra/docs/clang-tidy`; + +describe('clang-tidy documentation URLs', () => { + it('points at the clang-tidy version in use', () => { + strictEqual( + getClangTidyDocumentationUrl('checks/readability/use-std-min-max.html', '19.1.0'), + 'https://releases.llvm.org/19.1.0/tools/clang/tools/extra/docs/clang-tidy/checks/readability/use-std-min-max.html'); + }); + + it('uses the .1.0 release of that major, since patch releases have no page', () => { + strictEqual( + getClangTidyDocumentationUrl('checks/readability/use-std-min-max.html', '23.1.1'), + 'https://releases.llvm.org/23.1.0/tools/clang/tools/extra/docs/clang-tidy/checks/readability/use-std-min-max.html'); + strictEqual( + getClangTidyDocumentationUrl('checks/misc/include-cleaner.html', '22.1.3'), + 'https://releases.llvm.org/22.1.0/tools/clang/tools/extra/docs/clang-tidy/checks/misc/include-cleaner.html'); + }); + + it('falls back to the bundled version when the version in use is unknown', () => { + strictEqual(getClangTidyDocumentationUrl('checks/misc/include-cleaner.html'), `${bundledDocUrl}/checks/misc/include-cleaner.html`); + strictEqual(getClangTidyDocumentationUrl('checks/misc/include-cleaner.html', ''), `${bundledDocUrl}/checks/misc/include-cleaner.html`); + strictEqual(getClangTidyDocumentationUrl('checks/misc/include-cleaner.html', '23.1'), `${bundledDocUrl}/checks/misc/include-cleaner.html`); + }); + + it('keeps the fallback on the release the bundled binary belongs to', () => { + // The fallback is only correct while it matches what the bundled clang-tidy would produce, + // which is the point of deriving it from the bundled version instead of a literal URL. + strictEqual( + getClangTidyDocumentationUrl('checks/misc/include-cleaner.html', bundledClangTidyVersion), + getClangTidyDocumentationUrl('checks/misc/include-cleaner.html')); + }); + + it('reads the version token clang-tidy reports, suffix included', () => { + // What `clang-tidy --version` prints. + strictEqual(clangTidyVersionFromOutput('LLVM (http://llvm.org/):\n LLVM version 19.1.0\n Optimized build.'), '19.1.0'); + strictEqual(clangTidyVersionFromOutput('LLVM (http://llvm.org/):\n LLVM version 24.0.0git\n Optimized build.'), '24.0.0git'); + strictEqual(clangTidyVersionFromOutput('LLVM version 19.1.0-rc1'), '19.1.0-rc1'); + strictEqual(clangTidyVersionFromOutput('no version here'), undefined); + }); + + it('falls back for a build whose release has no documentation page yet', () => { + // 24.0.0git would otherwise produce a 24.1.0 URL, and that page does not exist until the + // 24.1.0 release ships; the same goes for a prerelease of a published major. + for (const version of ['24.0.0git', '19.1.0-rc1', '25.0.0svn']) { + strictEqual( + getClangTidyDocumentationUrl('checks/readability/use-std-min-max.html', version), + `${bundledDocUrl}/checks/readability/use-std-min-max.html`, + version); + } + }); +}); diff --git a/Extension/test/unit/clangTidyVersion.test.ts b/Extension/test/unit/clangTidyVersion.test.ts new file mode 100644 index 000000000..67393c32b --- /dev/null +++ b/Extension/test/unit/clangTidyVersion.test.ts @@ -0,0 +1,127 @@ +/* -------------------------------------------------------------------------------------------- + * Copyright (c) Microsoft Corporation. All Rights Reserved. + * See 'LICENSE' in the project root for license information. + * ------------------------------------------------------------------------------------------ */ + +import { beforeEach, describe, it } from 'mocha'; +import { strictEqual } from 'node:assert'; +import { readFileSync } from 'node:fs'; +import { resolve } from 'node:path'; +import type { Uri, WorkspaceFolder } from 'vscode'; +import proxyquire = require('proxyquire'); + +// The version reported by the auto-discovered clang-tidy, as settings.ts would cache it. +let cachedVersion: string | undefined; +// codeAnalysis.clangTidy.path per folder: undefined means the folder relies on auto-discovery. +let folderPaths: Map; +let workspaceFolders: WorkspaceFolder[] | undefined; + +const packageJson = JSON.parse(readFileSync(resolve(__dirname, '../../package.json'), 'utf8')); + +function folderOf(resource: unknown): string | undefined { + const uri: any = resource; + return uri?.fsPath; +} + +const configuration = { + get: (key: string) => { + // Only codeAnalysis.clangTidy.path is read by the getter under test. + if (key === 'codeAnalysis.clangTidy.path') { + return undefined; + } + return undefined; + }, + inspect: () => ({ defaultValue: undefined }) +}; + +const vscode = { + extensions: { getExtension: () => ({ packageJSON: packageJson }) }, + workspace: { + getConfiguration: (_section: string, resource: unknown) => { + const fsPath = folderOf(resource); + return { + get: (key: string) => { + if (key === 'codeAnalysis.clangTidy.path') { + return fsPath ? folderPaths.get(fsPath) : undefined; + } + return undefined; + }, + inspect: () => ({ defaultValue: undefined }) + }; + }, + get workspaceFolders() { + return workspaceFolders; + } + }, + ConfigurationTarget: { Global: 1, Workspace: 2, WorkspaceFolder: 3 } +}; + +const load = proxyquire.noCallThru(); +const common: typeof import('../../src/common') = load('../../src/common', { + vscode, + 'vscode-languageclient': {}, + 'vscode-tas-client': {}, + './logger': {}, + './platform': {}, + './telemetry': {} +}); + +// getCachedClangTidyVersion is replaced after loading, so the module keeps its own state. +const { CppSettings }: typeof import('../../src/LanguageServer/settings') = load('../../src/LanguageServer/settings', { + vscode, + '../common': { ...common, getCachedClangTidyVersion: () => cachedVersion }, + '../telemetry': {}, + './client': {}, + './editorConfig': {}, + './extension': {}, + './persistentState': {}, + './languageConfig': {} +}); + +function folder(fsPath: string): WorkspaceFolder { + return { uri: { fsPath, scheme: 'file' } as Uri, name: fsPath, index: 0 }; +} + +function settingsFor(fsPath: string): InstanceType { + return new CppSettings({ fsPath, scheme: 'file' } as Uri); +} + +describe('clang-tidy version per resource', () => { + beforeEach(() => { + cachedVersion = '24.0.0'; + folderPaths = new Map(); + workspaceFolders = undefined; + void configuration; + }); + + it('reports the auto-discovered version when no folder overrides the path', () => { + workspaceFolders = [folder('/a')]; + folderPaths.set('/a', undefined); + strictEqual(settingsFor('/a').clangTidyVersion, '24.0.0'); + }); + + it('reports nothing for a folder that sets its own clang-tidy path', () => { + workspaceFolders = [folder('/a')]; + folderPaths.set('/a', '/opt/llvm-19/bin/clang-tidy'); + strictEqual(settingsFor('/a').clangTidyVersion, undefined); + }); + + it('reports nothing in a multi-root workspace where another folder overrides the path', () => { + // Folder /a runs its own clang-tidy 19, /b relies on discovery. A translation unit from + // /a can report a header under /b, and the diagnostic only carries the header's URI, so + // the cached auto-discovered version says nothing about which binary ran. Falling back is + // the only safe answer. + workspaceFolders = [folder('/a'), folder('/b')]; + folderPaths.set('/a', '/opt/llvm-19/bin/clang-tidy'); + folderPaths.set('/b', undefined); + strictEqual(settingsFor('/b').clangTidyVersion, undefined); + }); + + it('still reports the version when every folder relies on auto-discovery', () => { + workspaceFolders = [folder('/a'), folder('/b')]; + folderPaths.set('/a', undefined); + folderPaths.set('/b', undefined); + strictEqual(settingsFor('/a').clangTidyVersion, '24.0.0'); + strictEqual(settingsFor('/b').clangTidyVersion, '24.0.0'); + }); +});