Fix for removing stale kits during Scan (#4856)

Omotola · mcodilla · web-flow · commit 7138e9eccf95 · 2026-04-06T22:23:36.000Z
* add new setting for removing stale  kits

* add new setting for removing stale  kits

* add accidentally removed scan

* readd accidentally removed scan

---------

Co-authored-by: MacGyver Codilla &lt;mcodilla@microsoft.com&gt;
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -36,6 +36,7 @@ Improvements:
 - Append `cmake` to diagnostics that this extension contributes to the Problems Pane. [PR #4766](https://github.com/microsoft/vscode-cmake-tools/pull/4766)
 - Set the `VSCODE_CMAKE_TOOLS` environment variable for all spawned subprocesses so that `CMakeLists.txt` can detect when CMake is run from VS Code. [#4233](https://github.com/microsoft/vscode-cmake-tools/issues/4233)
 - Honor `debugger.workingDirectory` from the CMake File API when debugging a target, so that the `DEBUGGER_WORKING_DIRECTORY` target property is used as the debugger working directory. [#4595](https://github.com/microsoft/vscode-cmake-tools/issues/4595)
+- Add `cmake.removeStaleKitsOnScan` setting to optionally remove stale compiler kits from the kit picker after a "Scan for Kits" when they are no longer rediscovered. This is useful after compiler upgrades that leave older versions outside `PATH`. Set `"keep": true` in a kit entry to prevent automatic removal. [#3852](https://github.com/microsoft/vscode-cmake-tools/issues/3852)
 - Add `pr-readiness` Copilot skill to verify PRs have a descriptive title, meaningful description, and a properly formatted CHANGELOG entry. [#4862](https://github.com/microsoft/vscode-cmake-tools/pull/4862)
 
 Bug Fixes:
diff --git a/docs/cmake-settings.md b/docs/cmake-settings.md
@@ -48,6 +48,7 @@ Options that support substitution, in the table below, allow variable references
 | `cmake.deleteBuildDirOnCleanConfigure` | If `true`, delete build directory during clean configure. | `false` | no |
 | `cmake.emscriptenSearchDirs` | List of paths to search for Emscripten. | `[]` | no |
 | `cmake.enableAutomaticKitScan` | Enable automatic kit scanning. | `true` | no |
+| `cmake.removeStaleKitsOnScan` | If `true`, a full **Scan for Kits** run removes compiler-based kits from `cmake-tools-kits.json` when they are no longer rediscovered. This is useful after compiler upgrades that leave older versions installed outside `PATH`. Set `"keep": true` in a kit entry to preserve it. This setting does not affect **Scan recursively for kits in specific directories**. | `false` | no |
 | `cmake.enabledOutputParsers` | List of enabled output parsers. | `["cmake", "gcc", "gnuld", "msvc", "ghs", "diab", "iwyu"]` | no |
 | `cmake.additionalBuildProblemMatchers` | Array of user-defined problem matchers for build output. Each entry has `name`, `regexp`, and optional capture group indices (`file`, `line`, `column`, `severity`, `message`, `code`). See [Additional Build Problem Matchers](#additional-build-problem-matchers) below. | `[]` | no |
 | `cmake.enableLanguageServices` | If `true`, enable CMake language services. | `true` | no |
diff --git a/docs/kits.md b/docs/kits.md
@@ -59,7 +59,9 @@ Update [user-local kits](#user-local-kits) by running **Scan for Kits** from the
 - The [user-local kit](#user-local-kits) `cmake-tools-kits.json` file is updated with the new kit information.
 
 > **Warning:**
-> The name of each kit is generated from the kit compiler and version information. Kits with the same name will be overwritten. To prevent custom kits from being overwritten, give them unique names. CMake Tools will not delete entries from `cmake-tools-kits.json`. It only adds and updates existing ones.
+> The name of each kit is generated from the kit compiler and version information. Kits with the same name will be overwritten. To prevent custom kits from being overwritten, give them unique names.
+>
+> By default, scans preserve existing entries in `cmake-tools-kits.json`. If `cmake.removeStaleKitsOnScan` is enabled, compiler-based kits (those with a `compilers` field) that are no longer rediscovered during a full scan are removed automatically. Set `"keep": true` in a kit entry to preserve it even when this cleanup is enabled. Kits without a `compilers` field (toolchain-only kits and Visual Studio kits) are always preserved.
 
 ## Kit options
 
diff --git a/package.json b/package.json
@@ -4112,6 +4112,12 @@
           "description": "%cmake-tools.configuration.cmake.enableAutomaticKitScan.description%",
           "scope": "resource"
         },
+        "cmake.removeStaleKitsOnScan": {
+          "type": "boolean",
+          "default": false,
+          "description": "%cmake-tools.configuration.cmake.removeStaleKitsOnScan.description%",
+          "scope": "window"
+        },
         "cmake.enableLanguageServices": {
           "type": "boolean",
           "default": true,
diff --git a/package.nls.json b/package.nls.json
@@ -380,6 +380,7 @@
         ]
     },
     "cmake-tools.configuration.cmake.enableAutomaticKitScan.description": "Enable automatic scanning for kits when a kit isn't selected. This will only take affect when CMake Presets aren't being used.",
+    "cmake-tools.configuration.cmake.removeStaleKitsOnScan.description": "Remove compiler-based kits from the user kits file during a full kit scan when they are no longer rediscovered. Set \"keep\": true in a kit entry to preserve it.",
     "cmake-tools.configuration.cmake.enableLanguageServices.description": "Enable language services for CMake files. This will enable syntax highlighting, code completion, and other features.",
     "cmake-tools.configuration.cmake.preRunCoverageTarget.description": "Target to build before running tests with coverage using the test explorer",
     "cmake-tools.configuration.cmake.postRunCoverageTarget.description": "Target to build after running tests with coverage using the test explorer",
diff --git a/src/config.ts b/src/config.ts
@@ -248,6 +248,7 @@ export interface ExtensionConfigurationSettings {
     automaticReconfigure: boolean;
     pinnedCommands: string[];
     enableAutomaticKitScan: boolean;
+    removeStaleKitsOnScan: boolean;
     enableLanguageServices: boolean;
     preRunCoverageTarget: string | null;
     postRunCoverageTarget: string | null;
@@ -642,6 +643,10 @@ export class ConfigurationReader implements vscode.Disposable {
         return this.configData.enableAutomaticKitScan;
     }
 
+    get removeStaleKitsOnScan(): boolean {
+        return this.configData.removeStaleKitsOnScan;
+    }
+
     get enableLanguageServices(): boolean {
         return this.configData.enableLanguageServices;
     }
@@ -740,6 +745,7 @@ export class ConfigurationReader implements vscode.Disposable {
         automaticReconfigure: new vscode.EventEmitter<boolean>(),
         pinnedCommands: new vscode.EventEmitter<string[]>(),
         enableAutomaticKitScan: new vscode.EventEmitter<boolean>(),
+        removeStaleKitsOnScan: new vscode.EventEmitter<boolean>(),
         enableLanguageServices: new vscode.EventEmitter<boolean>(),
         preRunCoverageTarget: new vscode.EventEmitter<string | null>(),
         postRunCoverageTarget: new vscode.EventEmitter<string | null>(),
diff --git a/src/extension.ts b/src/extension.ts
@@ -1091,7 +1091,9 @@ export class ExtensionManager implements vscode.Disposable {
             }
         }
 
-        const duplicateRemoved = await KitsController.scanForKits(cmakePath);
+        const duplicateRemoved = await KitsController.scanForKits(cmakePath, {
+            removeStaleCompilerKits: this.workspaceConfig.removeStaleKitsOnScan
+        });
         if (duplicateRemoved) {
             // Check each project. If there is an active kit set and if it is of the old definition, unset the kit.
             for (const project of this.projectController.getAllCMakeProjects()) {
diff --git a/src/kits/kit.ts b/src/kits/kit.ts
@@ -1341,7 +1341,9 @@ export async function scanForKitsIfNeeded(project: CMakeProject): Promise<boolea
 
         // action === 'scan'
         log.info(localize('silent.kits.rescan', 'Detected kits definition version change from {0} to {1}. Silently scanning for kits.', kitsVersionSaved, kitsVersionCurrent));
-        await kitsController.KitsController.scanForKits(await project.getCMakePathofProject());
+        await kitsController.KitsController.scanForKits(await project.getCMakePathofProject(), {
+            removeStaleCompilerKits: project.workspaceContext.config.removeStaleKitsOnScan
+        });
         await project.workspaceContext.state.extensionContext.globalState.update('kitsVersionSaved', kitsVersionCurrent);
         return true;
     } finally {
diff --git a/src/kits/kitsController.ts b/src/kits/kitsController.ts
@@ -35,6 +35,24 @@ export enum KitsReadMode {
     allAvailable
 }
 
+export interface ScanForKitsControllerOptions {
+    directoriesToScan?: string[];
+    removeStaleCompilerKits?: boolean;
+}
+
+export function shouldKeepUserKitAfterScan(kit: Kit, discoveredKitNames: ReadonlySet<string>, removeStaleCompilerKits: boolean): boolean {
+    if (!removeStaleCompilerKits) {
+        return true;
+    }
+    if (!kit.compilers) {
+        return true;
+    }
+    if (kit.keep === true) {
+        return true;
+    }
+    return discoveredKitNames.has(kit.name);
+}
+
 // TODO: migrate all kit related things in extension.ts to this class.
 export class KitsController {
     static additionalCompilerSearchDirs: string[] | undefined;
@@ -229,7 +247,9 @@ export class KitsController {
         // We don't have any kits defined. Scan for kits
         if (!KitsController.checkingHaveKits) {
             KitsController.checkingHaveKits = true;
-            await KitsController.scanForKits(await this.project.getCMakePathofProject());
+            await KitsController.scanForKits(await this.project.getCMakePathofProject(), {
+                removeStaleCompilerKits: this.project.workspaceContext.config.removeStaleKitsOnScan
+            });
             KitsController.checkingHaveKits = false;
             return true;
         } else {
@@ -289,7 +309,9 @@ export class KitsController {
             return false;
         } else {
             if (chosen_kit.kit.name === SpecialKits.ScanForKits) {
-                await KitsController.scanForKits(await this.project.getCMakePathofProject());
+                await KitsController.scanForKits(await this.project.getCMakePathofProject(), {
+                    removeStaleCompilerKits: this.project.workspaceContext.config.removeStaleKitsOnScan
+                });
                 return false;
             } else if (chosen_kit.kit.name === SpecialKits.ScanSpecificDir) {
                 await KitsController.scanForKitsInSpecificFolder(this.project);
@@ -507,9 +529,12 @@ export class KitsController {
      *
      * @returns if any duplicate vs kits are removed.
      */
-    static async scanForKits(cmakePath: string, directoriesToScan?: string[]) {
+    static async scanForKits(cmakePath: string, options?: ScanForKitsControllerOptions) {
         log.debug(localize('rescanning.for.kits', 'Rescanning for kits'));
 
+        const directoriesToScan = options?.directoriesToScan;
+        const removeStaleCompilerKits = options?.removeStaleCompilerKits === true && !directoriesToScan;
+
         // Do the scan:
         const discovered_kits = await scanForKits(cmakePath, !!directoriesToScan ? {
             scanDirs: directoriesToScan,
@@ -570,7 +595,15 @@ export class KitsController {
             old_kits_by_name
         );
 
-        const new_kits = Object.keys(new_kits_by_name).map(k => new_kits_by_name[k]);
+        // Build the set of kit names found in this scan so we can drop stale entries.
+        const discovered_kit_names = new Set(discovered_kits.map(k => k.name));
+
+        // Optionally remove compiler-based kits that were not rediscovered in a
+        // full scan. Partial scans of specific directories never remove existing
+        // kits because they do not represent the full discovery set.
+        const new_kits = Object.keys(new_kits_by_name)
+            .map(k => new_kits_by_name[k])
+            .filter(kit => shouldKeepUserKitAfterScan(kit, discovered_kit_names, removeStaleCompilerKits));
         KitsController.userKits = new_kits;
         await KitsController._writeUserKitsFile(cmakePath, new_kits);
 
@@ -622,10 +655,9 @@ export class KitsController {
             }
         );
 
-        await KitsController.scanForKits(
-            await project.getCMakePathofProject(),
-            accumulatedDirs
-        );
+        await KitsController.scanForKits(await project.getCMakePathofProject(), {
+            directoriesToScan: accumulatedDirs
+        });
     }
 
     static isBetterMatch(newKit: Kit, existingKit?: Kit): boolean {
diff --git a/src/presets/presetsController.ts b/src/presets/presetsController.ts
@@ -377,7 +377,9 @@ export class PresetsController implements vscode.Disposable {
                         return false;
                     } else {
                         if (chosen_kit.kit.name === SpecialKits.ScanForKits) {
-                            await KitsController.scanForKits(await this.project.getCMakePathofProject());
+                            await KitsController.scanForKits(await this.project.getCMakePathofProject(), {
+                                removeStaleCompilerKits: this.project.workspaceContext.config.removeStaleKitsOnScan
+                            });
                             return false;
                         } else if (chosen_kit.kit.name === SpecialKits.ScanSpecificDir) {
                             await KitsController.scanForKitsInSpecificFolder(this.project);
diff --git a/test/unit-tests/config.test.ts b/test/unit-tests/config.test.ts
@@ -82,6 +82,7 @@ function createConfig(conf: Partial<ExtensionConfigurationSettings>): Configurat
         ignoreCMakeListsMissing: false,
         automaticReconfigure: false,
         enableAutomaticKitScan: true,
+        removeStaleKitsOnScan: false,
         enableLanguageServices: true,
         preRunCoverageTarget: null,
         postRunCoverageTarget: null,
@@ -186,4 +187,16 @@ suite('Configuration', () => {
         conf.updatePartial({ shell: '/usr/bin/bash' });
         expect(conf.shell).to.eq('/usr/bin/bash');
     });
+
+    test('Read removeStaleKitsOnScan as false by default', () => {
+        const conf = createConfig({});
+        expect(conf.removeStaleKitsOnScan).to.be.false;
+    });
+
+    test('Update removeStaleKitsOnScan setting', () => {
+        const conf = createConfig({ removeStaleKitsOnScan: false });
+        expect(conf.removeStaleKitsOnScan).to.be.false;
+        conf.updatePartial({ removeStaleKitsOnScan: true });
+        expect(conf.removeStaleKitsOnScan).to.be.true;
+    });
 });
diff --git a/test/unit-tests/kit-scan.test.ts b/test/unit-tests/kit-scan.test.ts
@@ -7,6 +7,7 @@ chai.use(chaiAsPromised);
 
 import { expect } from 'chai';
 import * as kit from '@cmt/kits/kit';
+import { shouldKeepUserKitAfterScan } from '@cmt/kits/kitsController';
 import * as triple from '@cmt/triple';
 import { fs } from '@cmt/pr';
 
@@ -348,4 +349,47 @@ suite('Kits scan test', () => {
             expect(action).to.eq('scan');
         });
     });
+
+    suite('shouldKeepUserKitAfterScan', () => {
+        test('preserves compiler kits when stale-kit cleanup is disabled', () => {
+            const existingKit: kit.Kit = {
+                name: 'My Custom GCC',
+                compilers: { C: 'C:/toolchains/gcc.exe' },
+                isTrusted: true
+            };
+
+            expect(shouldKeepUserKitAfterScan(existingKit, new Set<string>(), false)).to.be.true;
+        });
+
+        test('drops compiler kits not rediscovered when stale-kit cleanup is enabled', () => {
+            const existingKit: kit.Kit = {
+                name: 'Old GCC',
+                compilers: { C: 'gcc' },
+                isTrusted: true
+            };
+
+            expect(shouldKeepUserKitAfterScan(existingKit, new Set<string>(), true)).to.be.false;
+        });
+
+        test('preserves keep:true compiler kits when stale-kit cleanup is enabled', () => {
+            const existingKit: kit.Kit = {
+                name: 'Pinned GCC',
+                compilers: { C: 'gcc' },
+                keep: true,
+                isTrusted: true
+            };
+
+            expect(shouldKeepUserKitAfterScan(existingKit, new Set<string>(), true)).to.be.true;
+        });
+
+        test('preserves non-compiler kits when stale-kit cleanup is enabled', () => {
+            const existingKit: kit.Kit = {
+                name: 'Toolchain only',
+                toolchainFile: 'toolchain.cmake',
+                isTrusted: true
+            };
+
+            expect(shouldKeepUserKitAfterScan(existingKit, new Set<string>(), true)).to.be.true;
+        });
+    });
 });

Original file line number	Diff line number	Diff line change
`@@ -380,6 +380,7 @@`
`380`	`380`	`]`
`381`	`381`	`},`
`382`	`382`	`"cmake-tools.configuration.cmake.enableAutomaticKitScan.description": "Enable automatic scanning for kits when a kit isn't selected. This will only take affect when CMake Presets aren't being used.",`
	`383`	`+ "cmake-tools.configuration.cmake.removeStaleKitsOnScan.description": "Remove compiler-based kits from the user kits file during a full kit scan when they are no longer rediscovered. Set \"keep\": true in a kit entry to preserve it.",`
`383`	`384`	`"cmake-tools.configuration.cmake.enableLanguageServices.description": "Enable language services for CMake files. This will enable syntax highlighting, code completion, and other features.",`
`384`	`385`	`"cmake-tools.configuration.cmake.preRunCoverageTarget.description": "Target to build before running tests with coverage using the test explorer",`
`385`	`386`	`"cmake-tools.configuration.cmake.postRunCoverageTarget.description": "Target to build after running tests with coverage using the test explorer",`
Original file line number	Diff line number	Diff line change
`@@ -1091,7 +1091,9 @@ export class ExtensionManager implements vscode.Disposable {`
`1091`	`1091`	`}`
`1092`	`1092`	`}`
`1093`	`1093`
`1094`		`- const duplicateRemoved = await KitsController.scanForKits(cmakePath);`
	`1094`	`+ const duplicateRemoved = await KitsController.scanForKits(cmakePath, {`
	`1095`	`+ removeStaleCompilerKits: this.workspaceConfig.removeStaleKitsOnScan`
	`1096`	`+ });`
`1095`	`1097`	`if (duplicateRemoved) {`
`1096`	`1098`	`// Check each project. If there is an active kit set and if it is of the old definition, unset the kit.`
`1097`	`1099`	`for (const project of this.projectController.getAllCMakeProjects()) {`