Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 9 additions & 2 deletions Extension/src/LanguageServer/Providers/codeActionProvider.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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<string> = new Set<string>();
const showClear: string = new CppSettings().clangTidyCodeActionShowClear;

// Check which code actions to show. This can get called a lot
Expand Down Expand Up @@ -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);
Expand Down
44 changes: 44 additions & 0 deletions Extension/src/LanguageServer/clangTidyDocumentation.ts
Original file line number Diff line number Diff line change
@@ -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;

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✨Copilot (devbox3-wsl/agent165): [Minor] An auto-discovered development build can report 24.0.0git; the version detection strips the suffix and caches 24.0.0, so this produces 24.1.0 links before that release exists. For example, the new link for readability-use-std-min-max returns 404 while the previous 23.1.0 link works. Could prerelease builds use a published documentation target instead, with a regression test for the detected version?

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Right, and the example checks out: 24.1.0 returns 404 today while 23.1.0 is there.

The version was matched with a bare three-number pattern and cached stripped, so a dev build's 24.0.0git became 24.0.0 and produced a release that does not exist yet. clangTidyVersionFromOutput now keeps the token as written, and documentationRelease only accepts a plain X.Y.Z, so anything with a suffix falls back to the bundled release.

Two tests: the token is read with its suffix, and 24.0.0git, 19.1.0-rc1 and 25.0.0svn all produce the bundled URL. Both fail before the change. I checked that 404/200 pair against releases.llvm.org rather than assuming it.

}

/**
* 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}`;
}
38 changes: 21 additions & 17 deletions Extension/src/LanguageServer/codeAnalysis.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -63,7 +65,6 @@ export interface CodeActionCodeInfo {
fixAllTypeCodeAction?: vscode.CodeAction;
disableAllTypeCodeAction?: vscode.CodeAction;
removeAllTypeCodeAction?: vscode.CodeAction;
docCodeAction?: vscode.CodeAction;
}

interface CodeActionAllInfo {
Expand Down Expand Up @@ -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);
Expand Down Expand Up @@ -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;
Expand Down
47 changes: 44 additions & 3 deletions Extension/src/LanguageServer/settings.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Expand Down Expand Up @@ -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);
}
Expand All @@ -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();
Expand All @@ -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);
}
}
}
Expand Down
9 changes: 9 additions & 0 deletions Extension/src/common.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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;

Expand Down
60 changes: 60 additions & 0 deletions Extension/test/unit/clangTidyDocumentation.test.ts
Original file line number Diff line number Diff line change
@@ -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);
}
});
});
Loading