Add validation and user notifications for malformed pythonProjects settings

src/features/projectManager.ts

@@ -16,6 +16,7 @@ import {
     getDefaultEnvManagerSetting,
     getDefaultPkgManagerSetting,
 } from './settings/settingHelpers';
+import { validateAndNotifyPythonProjectsSettings } from './settings/settingsValidation';
 
 type ProjectArray = PythonProject[];
 
@@ -30,6 +31,12 @@ export class PythonProjectManagerImpl implements PythonProjectManager {
 
     initialize(): void {
         this.add(this.getInitialProjects());
+
+        // Validate pythonProjects settings on initialization
+        validateAndNotifyPythonProjectsSettings().catch(() => {
+            // Error logging handled in validation function
+        });
+
         this.disposables.push(
             this._onDidChangeProjects,
             new Disposable(() => this._projects.clear()),
@@ -43,6 +50,13 @@ export class PythonProjectManagerImpl implements PythonProjectManager {
                     e.affectsConfiguration('python-envs.defaultPackageManager')
                 ) {
                     this.updateDebounce.trigger();
+
+                    // Validate settings when pythonProjects configuration changes
+                    if (e.affectsConfiguration('python-envs.pythonProjects')) {
+                        validateAndNotifyPythonProjectsSettings().catch(() => {
+                            // Error logging handled in validation function
+                        });
+                    }
                 }
             }),
         );
@@ -65,8 +79,19 @@ export class PythonProjectManagerImpl implements PythonProjectManager {
                 newProjects.push(new PythonProjectsImpl(w.name, w.uri));
             }
 
+            // Validate that overrides is an array
+            if (!Array.isArray(overrides)) {
+                // Skip processing if the setting is invalid
+                continue;
+            }
+
             // For each override, resolve its path and add as a project if not already present
             for (const o of overrides) {
+                // Skip invalid entries (missing required fields)
+                if (!o || typeof o !== 'object' || !o.path || !o.envManager || !o.packageManager) {
+                    continue;
+                }
+
                 let uriFromWorkspace: Uri | undefined = undefined;
                 // if override has a workspace property, resolve the path relative to that workspace
                 if (o.workspace) {

src/features/settings/settingsValidation.ts

@@ -0,0 +1,185 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import { commands, ConfigurationTarget, l10n, Uri, workspace } from 'vscode';
+import { traceError, traceWarn } from '../../common/logging';
+import { getGlobalPersistentState } from '../../common/persistentState';
+import { showWarningMessage } from '../../common/window.apis';
+import { getConfiguration, getWorkspaceFolders } from '../../common/workspace.apis';
+import { PythonProjectSettings } from '../../internal.api';
+
+const DONT_SHOW_INVALID_SETTINGS_KEY = 'dontShowInvalidPythonProjectSettings';
+
+interface InvalidProjectEntry {
+    entry: PythonProjectSettings;
+    workspaceUri: Uri;
+    reason: string;
+}
+
+/**
+ * Validates a single PythonProjectSettings entry
+ * @param entry The settings entry to validate
+ * @returns An error message if invalid, undefined if valid
+ */
+function validateProjectEntry(entry: PythonProjectSettings): string | undefined {
+    // Check if entry is a valid object (not a string, array, null, or other primitive)
+    if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
+        return l10n.t('Invalid entry format: expected object');
+    }
+
+    // Check if required fields exist
+    if (!entry.path) {
+        return l10n.t('Missing required field: path');
+    }
+
+    if (!entry.envManager) {
+        return l10n.t('Missing required field: envManager');
+    }
+
+    if (!entry.packageManager) {
+        return l10n.t('Missing required field: packageManager');
+    }
+
+    return undefined;
+}
+
+/**
+ * Validates all pythonProjects settings across all workspaces
+ * @returns Array of invalid entries with their details
+ */
+export function validatePythonProjectsSettings(): InvalidProjectEntry[] {
+    const invalidEntries: InvalidProjectEntry[] = [];
+    const workspaces = getWorkspaceFolders() ?? [];
+
+    for (const workspace of workspaces) {
+        const config = getConfiguration('python-envs', workspace.uri);
+        const projectSettings = config.get<PythonProjectSettings[]>('pythonProjects', []);
+
+        // Check if the setting is valid (should be an array)
+        if (!Array.isArray(projectSettings)) {
+            traceError(
+                `Invalid pythonProjects setting in workspace ${workspace.name}: expected array, got ${typeof projectSettings}`,
+            );
+            invalidEntries.push({
+                entry: projectSettings as unknown as PythonProjectSettings,
+                workspaceUri: workspace.uri,
+                reason: l10n.t('Invalid format: pythonProjects must be an array'),
+            });
+            continue;
+        }
+
+        // Validate each entry
+        for (const entry of projectSettings) {
+            const error = validateProjectEntry(entry);
+            if (error) {
+                traceWarn(`Invalid pythonProjects entry in workspace ${workspace.name}:`, entry, error);
+                invalidEntries.push({
+                    entry,
+                    workspaceUri: workspace.uri,
+                    reason: error,
+                });
+            }
+        }
+    }
+
+    return invalidEntries;
+}
+
+/**
+ * Shows a warning notification about invalid pythonProjects settings
+ * Provides options to remove the invalid entry, open settings, or don't show again
+ * @param invalidEntries Array of invalid entries found
+ */
+export async function notifyInvalidPythonProjectsSettings(invalidEntries: InvalidProjectEntry[]): Promise<void> {
+    if (invalidEntries.length === 0) {
+        return;
+    }
+
+    // Check if user has chosen to not show this warning again
+    const persistentState = await getGlobalPersistentState();
+    const dontShowAgain = await persistentState.get<boolean>(DONT_SHOW_INVALID_SETTINGS_KEY, false);
+
+    if (dontShowAgain) {
+        traceWarn('Not showing invalid pythonProjects settings warning due to user preference');
+        return;
+    }
+
+    // Create a descriptive message
+    const count = invalidEntries.length;
+    const message =
+        count === 1
+            ? l10n.t(
+                  'Found an invalid entry in python-envs.pythonProjects settings. This may cause issues with project detection.',
+              )
+            : l10n.t(
+                  'Found {0} invalid entries in python-envs.pythonProjects settings. This may cause issues with project detection.',
+                  count,
+              );
+
+    // Show warning with options
+    const removeOption = l10n.t('Remove Invalid Entry');
+    const openSettingsOption = l10n.t('Open Settings');
+    const dontShowOption = l10n.t("Don't Show Again");
+
+    const choice = await showWarningMessage(message, removeOption, openSettingsOption, dontShowOption);
+
+    if (choice === removeOption) {
+        // Remove the first invalid entry (or all if multiple)
+        try {
+            // Group by workspace to batch updates
+            const byWorkspace = new Map<string, InvalidProjectEntry[]>();
+            for (const invalid of invalidEntries) {
+                const key = invalid.workspaceUri.toString();
+                if (!byWorkspace.has(key)) {
+                    byWorkspace.set(key, []);
+                }
+                byWorkspace.get(key)!.push(invalid);
+            }
+
+            // Remove invalid entries from each workspace
+            for (const [workspaceKey, entries] of byWorkspace) {
+                const workspaceUri = Uri.parse(workspaceKey);
+                const config = getConfiguration('python-envs', workspaceUri);
+                let projectSettings = config.get<PythonProjectSettings[]>('pythonProjects', []);
+
+                if (!Array.isArray(projectSettings)) {
+                    await config.update('pythonProjects', [], ConfigurationTarget.Workspace);
+                    continue;
+                }
+
+                // Filter out all invalid entries
+                const invalidJsonStrings = new Set(entries.map((e) => JSON.stringify(e.entry)));
+                projectSettings = projectSettings.filter((e) => !invalidJsonStrings.has(JSON.stringify(e)));
+
+                await config.update('pythonProjects', projectSettings, ConfigurationTarget.Workspace);
+            }
+
+            traceWarn(`Removed ${invalidEntries.length} invalid pythonProjects entries`);
+        } catch (error) {
+            traceError('Failed to remove invalid entries:', error);
+            await showWarningMessage(l10n.t('Failed to remove invalid entries. Please check the logs for details.'));
+        }
+    } else if (choice === openSettingsOption) {
+        // Open settings UI to the pythonProjects setting
+        await commands.executeCommand('workbench.action.openSettings', '@ext:ms-python.vscode-python-envs pythonProjects');
+    } else if (choice === dontShowOption) {
+        // Save preference to not show again
+        await persistentState.set(DONT_SHOW_INVALID_SETTINGS_KEY, true);
+        traceWarn('User chose to not show invalid pythonProjects settings warning again');
+    }
+}
+
+/**
+ * Validates pythonProjects settings and shows a notification if invalid entries are found
+ * Should be called when the extension initializes or when settings change
+ */
+export async function validateAndNotifyPythonProjectsSettings(): Promise<void> {
+    try {
+        const invalidEntries = validatePythonProjectsSettings();
+        if (invalidEntries.length > 0) {
+            await notifyInvalidPythonProjectsSettings(invalidEntries);
+        }
+    } catch (error) {
+        traceError('Error validating pythonProjects settings:', error);
+    }
+}