From 827d7024ae1775b9903bffceba4a8100cfbdc629 Mon Sep 17 00:00:00 2001 From: abdelhadi703 Date: Sun, 11 Oct 2026 14:55:48 +0200 Subject: [PATCH 1/4] Use the clang-tidy version in use for check documentation links --- .../LanguageServer/clangTidyDocumentation.ts | 19 +++++++++++++++ Extension/src/LanguageServer/codeAnalysis.ts | 4 ++-- Extension/src/LanguageServer/settings.ts | 15 +++++++++++- Extension/src/common.ts | 9 +++++++ .../test/unit/clangTidyDocumentation.test.ts | 24 +++++++++++++++++++ 5 files changed, 68 insertions(+), 3 deletions(-) create mode 100644 Extension/src/LanguageServer/clangTidyDocumentation.ts create mode 100644 Extension/test/unit/clangTidyDocumentation.test.ts diff --git a/Extension/src/LanguageServer/clangTidyDocumentation.ts b/Extension/src/LanguageServer/clangTidyDocumentation.ts new file mode 100644 index 000000000..6915ad775 --- /dev/null +++ b/Extension/src/LanguageServer/clangTidyDocumentation.ts @@ -0,0 +1,19 @@ +/* -------------------------------------------------------------------------------------------- + * Copyright (c) Microsoft Corporation. All Rights Reserved. + * See 'LICENSE' in the project root for license information. + * ------------------------------------------------------------------------------------------ */ + +/** + * The clang-tidy documentation is published for every LLVM release, so the URL of a check's + * page depends on the release the clang-tidy binary in use comes from. Checks added in a + * newer release have no page at all in an older one. When the version in use could not be + * determined, fall back to the release bundled with the extension. + */ +export const fallbackClangTidyDocVersion: string = '23.1.0'; + +const versionPattern: RegExp = /^[0-9]+\.[0-9]+\.[0-9]+$/; + +export function getClangTidyDocumentationUrl(docPage: string, clangTidyVersion?: string): string { + const version: string = clangTidyVersion && versionPattern.test(clangTidyVersion) ? clangTidyVersion : fallbackClangTidyDocVersion; + return `https://releases.llvm.org/${version}/tools/clang/tools/extra/docs/clang-tidy/${docPage}`; +} diff --git a/Extension/src/LanguageServer/codeAnalysis.ts b/Extension/src/LanguageServer/codeAnalysis.ts index 61cc8cf06..c911573df 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'; @@ -379,8 +380,7 @@ 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, new CppSettings().clangTidyVersion)); diagnostic.code = { value: identifier.code, target: primaryDocUri }; if (new CppSettings().clangTidyCodeActionShowDocumentation) { diff --git a/Extension/src/LanguageServer/settings.ts b/Extension/src/LanguageServer/settings.ts index 499431d09..50bacb00e 100644 --- a/Extension/src/LanguageServer/settings.ts +++ b/Extension/src/LanguageServer/settings.ts @@ -12,7 +12,7 @@ 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'; @@ -279,6 +279,10 @@ export class CppSettings extends Settings { return this.getClangPath(false); } + public get clangTidyVersion(): string | undefined { + return getCachedClangTidyVersion(); + } + public get clangFormatPath(): string | undefined { return this.getClangPath(true); } @@ -303,6 +307,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(); @@ -322,10 +327,18 @@ export class CppSettings extends Settings { if (semver.ltr(userVersion, 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..70437745e --- /dev/null +++ b/Extension/test/unit/clangTidyDocumentation.test.ts @@ -0,0 +1,24 @@ +/* -------------------------------------------------------------------------------------------- + * 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 { 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('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`); + }); +}); From ca83b431bf6a5b93c97d01695c0521e0f69c46f2 Mon Sep 17 00:00:00 2001 From: abdelhadi703 Date: Wed, 14 Oct 2026 00:35:41 +0200 Subject: [PATCH 2/4] Use the .1.0 release of the clang-tidy major for documentation links Only the .1.0 release of each major has a published documentation page: 23.1.0 and 22.1.0 answer, 23.1.1 and 22.1.3 return 404. The version in use is reduced to its major.1.0 release before it goes into the URL. Also drops the changelog entry, since those are written separately before a release, and stops reporting the cached version for a resource that sets its own codeAnalysis.clangTidy.path -- that cached version comes from a binary the resource is not running. --- .../LanguageServer/clangTidyDocumentation.ts | 21 ++++++++++++------- Extension/src/LanguageServer/codeAnalysis.ts | 2 +- Extension/src/LanguageServer/settings.ts | 6 +++++- .../test/unit/clangTidyDocumentation.test.ts | 9 ++++++++ 4 files changed, 29 insertions(+), 9 deletions(-) diff --git a/Extension/src/LanguageServer/clangTidyDocumentation.ts b/Extension/src/LanguageServer/clangTidyDocumentation.ts index 6915ad775..1c9a30b1e 100644 --- a/Extension/src/LanguageServer/clangTidyDocumentation.ts +++ b/Extension/src/LanguageServer/clangTidyDocumentation.ts @@ -4,16 +4,23 @@ * ------------------------------------------------------------------------------------------ */ /** - * The clang-tidy documentation is published for every LLVM release, so the URL of a check's - * page depends on the release the clang-tidy binary in use comes from. Checks added in a - * newer release have no page at all in an older one. When the version in use could not be - * determined, fall back to the release bundled with the extension. + * 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. */ export const fallbackClangTidyDocVersion: string = '23.1.0'; -const versionPattern: RegExp = /^[0-9]+\.[0-9]+\.[0-9]+$/; +const versionPattern: RegExp = /^([0-9]+)\.[0-9]+\.[0-9]+$/; + +/** 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; +} export function getClangTidyDocumentationUrl(docPage: string, clangTidyVersion?: string): string { - const version: string = clangTidyVersion && versionPattern.test(clangTidyVersion) ? clangTidyVersion : fallbackClangTidyDocVersion; - return `https://releases.llvm.org/${version}/tools/clang/tools/extra/docs/clang-tidy/${docPage}`; + 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 c911573df..e6f7a2b23 100644 --- a/Extension/src/LanguageServer/codeAnalysis.ts +++ b/Extension/src/LanguageServer/codeAnalysis.ts @@ -380,7 +380,7 @@ export function publishCodeAnalysisDiagnostics(params: PublishCodeAnalysisDiagno const checksPage: string = dashIndex > 0 ? primaryCode.substring(dashIndex + 1) : primaryCode; docPage = `checks${checksGroup}/${checksPage}.html`; } - const primaryDocUri: vscode.Uri = vscode.Uri.parse(getClangTidyDocumentationUrl(docPage, new CppSettings().clangTidyVersion)); + const primaryDocUri: vscode.Uri = vscode.Uri.parse(getClangTidyDocumentationUrl(docPage, new CppSettings(realUri).clangTidyVersion)); diagnostic.code = { value: identifier.code, target: primaryDocUri }; if (new CppSettings().clangTidyCodeActionShowDocumentation) { diff --git a/Extension/src/LanguageServer/settings.ts b/Extension/src/LanguageServer/settings.ts index 50bacb00e..c5916dbdc 100644 --- a/Extension/src/LanguageServer/settings.ts +++ b/Extension/src/LanguageServer/settings.ts @@ -280,7 +280,11 @@ export class CppSettings extends Settings { } public get clangTidyVersion(): string | undefined { - return getCachedClangTidyVersion(); + // 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. + return changeBlankStringToUndefined(this.getAsStringOrUndefined("codeAnalysis.clangTidy.path")) ? undefined : getCachedClangTidyVersion(); } public get clangFormatPath(): string | undefined { diff --git a/Extension/test/unit/clangTidyDocumentation.test.ts b/Extension/test/unit/clangTidyDocumentation.test.ts index 70437745e..a6fccc710 100644 --- a/Extension/test/unit/clangTidyDocumentation.test.ts +++ b/Extension/test/unit/clangTidyDocumentation.test.ts @@ -16,6 +16,15 @@ describe('clang-tidy documentation URLs', () => { '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`); From 321365d54b51e20e5b9384808bbda817b6bd37c7 Mon Sep 17 00:00:00 2001 From: abdelhadi703 Date: Sat, 31 Oct 2026 15:49:36 +0100 Subject: [PATCH 3/4] Keep the documentation action with its resource The action was cached per check code, so the first folder to report a code decided the documentation release for every folder, and the URL stayed put after the clang-tidy path or version changed. It now travels with the diagnostic, and the provider keeps one action per target URL. The fallback release is derived from the bundled version instead of spelling out 23.1.0, so bumping the bundled binary moves it too. --- .../Providers/codeActionProvider.ts | 11 +++++-- .../LanguageServer/clangTidyDocumentation.ts | 10 +++++-- Extension/src/LanguageServer/codeAnalysis.ts | 29 +++++++++---------- .../test/unit/clangTidyDocumentation.test.ts | 10 ++++++- 4 files changed, 40 insertions(+), 20 deletions(-) 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 index 1c9a30b1e..3b7c41ec2 100644 --- a/Extension/src/LanguageServer/clangTidyDocumentation.ts +++ b/Extension/src/LanguageServer/clangTidyDocumentation.ts @@ -10,8 +10,6 @@ * 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. */ -export const fallbackClangTidyDocVersion: string = '23.1.0'; - const versionPattern: RegExp = /^([0-9]+)\.[0-9]+\.[0-9]+$/; /** The release a clang-tidy version's documentation was published under. */ @@ -20,6 +18,14 @@ function documentationRelease(clangTidyVersion: string): string | undefined { 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 e6f7a2b23..957f152e3 100644 --- a/Extension/src/LanguageServer/codeAnalysis.ts +++ b/Extension/src/LanguageServer/codeAnalysis.ts @@ -35,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, @@ -64,7 +65,6 @@ export interface CodeActionCodeInfo { fixAllTypeCodeAction?: vscode.CodeAction; disableAllTypeCodeAction?: vscode.CodeAction; removeAllTypeCodeAction?: vscode.CodeAction; - docCodeAction?: vscode.CodeAction; } interface CodeActionAllInfo { @@ -383,20 +383,19 @@ export function publishCodeAnalysisDiagnostics(params: PublishCodeAnalysisDiagno const primaryDocUri: vscode.Uri = vscode.Uri.parse(getClangTidyDocumentationUrl(docPage, new CppSettings(realUri).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 (new CppSettings(realUri).clangTidyCodeActionShowDocumentation) { + 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/test/unit/clangTidyDocumentation.test.ts b/Extension/test/unit/clangTidyDocumentation.test.ts index a6fccc710..7cecf13f7 100644 --- a/Extension/test/unit/clangTidyDocumentation.test.ts +++ b/Extension/test/unit/clangTidyDocumentation.test.ts @@ -5,7 +5,7 @@ import { describe, it } from 'mocha'; import { strictEqual } from 'node:assert'; -import { fallbackClangTidyDocVersion, getClangTidyDocumentationUrl } from '../../src/LanguageServer/clangTidyDocumentation'; +import { bundledClangTidyVersion, fallbackClangTidyDocVersion, getClangTidyDocumentationUrl } from '../../src/LanguageServer/clangTidyDocumentation'; const bundledDocUrl: string = `https://releases.llvm.org/${fallbackClangTidyDocVersion}/tools/clang/tools/extra/docs/clang-tidy`; @@ -30,4 +30,12 @@ describe('clang-tidy documentation URLs', () => { 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')); + }); }); From c4450255a20b8554306994f21ee1f6410cba8173 Mon Sep 17 00:00:00 2001 From: Abdelhadi Salmaoui Date: Sun, 22 Nov 2026 00:57:23 +0100 Subject: [PATCH 4/4] Fall back to a published release for builds without documentation A development build reports its version with a suffix (24.0.0git), and the version was cached with the suffix stripped, so the URL came out as 24.1.0 -- a release that does not exist yet, a 404. The token is now kept as written and anything that is not a plain X.Y.Z falls back to the bundled release. The version was also resolved from the diagnostic file's own settings, which misses a translation unit from one folder reporting a header under another: there the folder of the header does not say which clang-tidy ran. When any folder in the workspace overrides the path, the cached auto-discovered version is not trusted and the fallback applies. --- .../LanguageServer/clangTidyDocumentation.ts | 12 ++ Extension/src/LanguageServer/codeAnalysis.ts | 9 +- Extension/src/LanguageServer/settings.ts | 30 ++++- .../test/unit/clangTidyDocumentation.test.ts | 21 ++- Extension/test/unit/clangTidyVersion.test.ts | 127 ++++++++++++++++++ 5 files changed, 193 insertions(+), 6 deletions(-) create mode 100644 Extension/test/unit/clangTidyVersion.test.ts diff --git a/Extension/src/LanguageServer/clangTidyDocumentation.ts b/Extension/src/LanguageServer/clangTidyDocumentation.ts index 3b7c41ec2..0f7fa1fc6 100644 --- a/Extension/src/LanguageServer/clangTidyDocumentation.ts +++ b/Extension/src/LanguageServer/clangTidyDocumentation.ts @@ -12,6 +12,18 @@ */ 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); diff --git a/Extension/src/LanguageServer/codeAnalysis.ts b/Extension/src/LanguageServer/codeAnalysis.ts index 957f152e3..86bf36895 100644 --- a/Extension/src/LanguageServer/codeAnalysis.ts +++ b/Extension/src/LanguageServer/codeAnalysis.ts @@ -257,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); @@ -380,13 +385,13 @@ export function publishCodeAnalysisDiagnostics(params: PublishCodeAnalysisDiagno const checksPage: string = dashIndex > 0 ? primaryCode.substring(dashIndex + 1) : primaryCode; docPage = `checks${checksGroup}/${checksPage}.html`; } - const primaryDocUri: vscode.Uri = vscode.Uri.parse(getClangTidyDocumentationUrl(docPage, new CppSettings(realUri).clangTidyVersion)); + const primaryDocUri: vscode.Uri = vscode.Uri.parse(getClangTidyDocumentationUrl(docPage, clangTidyVersion)); diagnostic.code = { value: identifier.code, target: primaryDocUri }; // 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 (new CppSettings(realUri).clangTidyCodeActionShowDocumentation) { + if (showDocumentation) { codeAction.docCodeAction = { title: localize("show.documentation.for", "Show documentation for {0}", primaryCode), command: { diff --git a/Extension/src/LanguageServer/settings.ts b/Extension/src/LanguageServer/settings.ts index c5916dbdc..3003b9ebf 100644 --- a/Extension/src/LanguageServer/settings.ts +++ b/Extension/src/LanguageServer/settings.ts @@ -16,6 +16,7 @@ import { getCachedClangFormatPath, getCachedClangTidyPath, getCachedClangTidyVer 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'; @@ -284,7 +285,27 @@ export class CppSettings extends Settings { // 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. - return changeBlankStringToUndefined(this.getAsStringOrUndefined("codeAnalysis.clangTidy.path")) ? undefined : getCachedClangTidyVersion(); + 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 { @@ -327,8 +348,11 @@ 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; diff --git a/Extension/test/unit/clangTidyDocumentation.test.ts b/Extension/test/unit/clangTidyDocumentation.test.ts index 7cecf13f7..09158644b 100644 --- a/Extension/test/unit/clangTidyDocumentation.test.ts +++ b/Extension/test/unit/clangTidyDocumentation.test.ts @@ -5,7 +5,7 @@ import { describe, it } from 'mocha'; import { strictEqual } from 'node:assert'; -import { bundledClangTidyVersion, fallbackClangTidyDocVersion, getClangTidyDocumentationUrl } from '../../src/LanguageServer/clangTidyDocumentation'; +import { bundledClangTidyVersion, clangTidyVersionFromOutput, fallbackClangTidyDocVersion, getClangTidyDocumentationUrl } from '../../src/LanguageServer/clangTidyDocumentation'; const bundledDocUrl: string = `https://releases.llvm.org/${fallbackClangTidyDocVersion}/tools/clang/tools/extra/docs/clang-tidy`; @@ -38,4 +38,23 @@ describe('clang-tidy documentation URLs', () => { 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'); + }); +});