refactor: update logging for default environment manager warnings and add localization support

Author: eleanorjboyd

.github/instructions/generic.instructions.md

@@ -0,0 +1,32 @@
+---
+applyTo: '**'
+---
+
+Provide project context and coding guidelines that AI should follow when generating code, answering questions, or reviewing changes.# Coding Instructions for vscode-python-environments
+
+## Localization
+
+-   Localize all user-facing messages using VS Code’s `l10n` API.
+-   Internal log messages do not require localization.
+
+## Logging
+
+-   Use the extension’s logging utilities (`traceLog`, `traceVerbose`) for internal logs.
+-   Do not use `console.log` or `console.warn` for logging.
+
+## Settings Precedence
+
+-   Always consider VS Code settings precedence:
+    1. Workspace folder
+    2. Workspace
+    3. User/global
+-   Remove or update settings from the highest precedence scope first.
+
+## Error Handling & User Notifications
+
+-   Avoid showing the same error message multiple times in a session; track state with a module-level variable.
+-   Use clear, actionable error messages and offer relevant buttons (e.g., "Open settings", "Close").
+
+## Documentation
+
+-   Add clear docstrings to public functions, describing their purpose, parameters, and behavior.

src/features/settings/settingHelpers.ts

@@ -9,7 +9,7 @@ import {
 } from 'vscode';
 import { PythonProject } from '../../api';
 import { DEFAULT_ENV_MANAGER_ID, DEFAULT_PACKAGE_MANAGER_ID } from '../../common/constants';
-import { traceError, traceInfo } from '../../common/logging';
+import { traceError, traceWarn } from '../../common/logging';
 import { getWorkspaceFile, getWorkspaceFolders } from '../../common/workspace.apis';
 import { PythonProjectManager, PythonProjectSettings } from '../../internal.api';
 
@@ -32,6 +32,7 @@ function getSettings(
 }
 
 let DEFAULT_ENV_MANAGER_BROKEN = false;
+let hasShownDefaultEnvManagerBrokenWarn = false;
 
 export function setDefaultEnvManagerBroken(broken: boolean) {
     DEFAULT_ENV_MANAGER_BROKEN = broken;
@@ -46,14 +47,18 @@ export function getDefaultEnvManagerSetting(wm: PythonProjectManager, scope?: Ur
     if (settings && settings.envManager.length > 0) {
         return settings.envManager;
     }
+    // Only show the warning once per session
     if (isDefaultEnvManagerBroken()) {
-        traceInfo(`Default environment manager is broken, using system default: ${DEFAULT_ENV_MANAGER_ID}`);
+        if (!hasShownDefaultEnvManagerBrokenWarn) {
+            traceWarn(`Default environment manager is broken, using system default: ${DEFAULT_ENV_MANAGER_ID}`);
+            hasShownDefaultEnvManagerBrokenWarn = true;
+        }
         return DEFAULT_ENV_MANAGER_ID;
     }
     const defaultManager = config.get<string>('defaultEnvManager');
     if (defaultManager === undefined || defaultManager === null || defaultManager === '') {
         traceError('No default environment manager set. Check setting python-envs.defaultEnvManager');
-        traceInfo(`Using system default package manager: ${DEFAULT_ENV_MANAGER_ID}`);
+        traceWarn(`Using system default package manager: ${DEFAULT_ENV_MANAGER_ID}`);
         return DEFAULT_ENV_MANAGER_ID;
     }
     return defaultManager;

src/managers/common/utils.ts

@@ -1,7 +1,8 @@
 import * as fs from 'fs-extra';
 import path from 'path';
-import { commands, ConfigurationTarget, window, workspace } from 'vscode';
+import { commands, ConfigurationTarget, l10n, window, workspace } from 'vscode';
 import { PythonCommandRunConfiguration, PythonEnvironment, PythonEnvironmentApi } from '../../api';
+import { traceLog, traceVerbose } from '../../common/logging';
 import { isWindows } from '../../common/utils/platformUtils';
 import { ShellConstants } from '../../features/common/shellConstants';
 import { getDefaultEnvManagerSetting, setDefaultEnvManagerBroken } from '../../features/settings/settingHelpers';
@@ -198,35 +199,64 @@ export async function getShellActivationCommands(binDir: string): Promise<{
     };
 }
 
+// Tracks if the broken defaultEnvManager error message has been shown this session
+let hasShownBrokenDefaultEnvManagerError = false;
+
+/**
+ * Checks if the given managerId is set as the default environment manager for the project.
+ * If so, marks the default manager as broken, refreshes environments, and shows an error message to the user.
+ * The error message offers to reset the setting, view the setting, or close.
+ * The error message is only shown once per session.
+ *
+ * @param managerId The environment manager id to check.
+ * @param projectManager The Python project manager instance.
+ * @param api The Python environment API instance.
+ */
 export async function notifyMissingManagerIfDefault(
     managerId: string,
     projectManager: PythonProjectManager,
     api: PythonEnvironmentApi,
 ) {
     const defaultEnvManager = getDefaultEnvManagerSetting(projectManager);
     if (defaultEnvManager === managerId) {
+        if (hasShownBrokenDefaultEnvManagerError) {
+            return;
+        }
+        hasShownBrokenDefaultEnvManagerError = true;
         setDefaultEnvManagerBroken(true);
         await api.refreshEnvironments(undefined);
         window
             .showErrorMessage(
-                `The default environment manager is set to '${defaultEnvManager}', but the ${
-                    managerId.split(':')[1]
-                } executable could not be found.`,
-                'Reset setting',
-                'View setting',
-                'Close',
+                l10n.t(
+                    "The default environment manager is set to '{0}', but the {1} executable could not be found.",
+                    defaultEnvManager,
+                    managerId.split(':')[1],
+                ),
+                l10n.t('Reset setting'),
+                l10n.t('View setting'),
+                l10n.t('Close'),
             )
-            .then((selection) => {
+            .then(async (selection) => {
                 if (selection === 'Reset setting') {
-                    // Remove the setting from all scopes
-                    const config = workspace.getConfiguration('python-envs');
-                    const inspect = config.inspect('defaultEnvManager');
-                    if (inspect?.workspaceValue !== undefined) {
-                        // Remove from workspace settings
-                        config.update('defaultEnvManager', undefined, ConfigurationTarget.Workspace);
-                    } else if (inspect?.globalValue !== undefined) {
-                        // Remove from user settings
-                        config.update('defaultEnvManager', undefined, ConfigurationTarget.Global);
+                    const result = await removeFirstDefaultEnvManagerSettingDetailed(managerId);
+                    if (!result.found) {
+                        window
+                            .showErrorMessage(
+                                l10n.t(
+                                    "Could not find a setting for 'defaultEnvManager' set to '{0}' to reset.",
+                                    managerId,
+                                ),
+                                l10n.t('Open settings'),
+                                l10n.t('Close'),
+                            )
+                            .then((sel) => {
+                                if (sel === 'Open settings') {
+                                    commands.executeCommand(
+                                        'workbench.action.openSettings',
+                                        'python-envs.defaultEnvManager',
+                                    );
+                                }
+                            });
                     }
                 }
                 if (selection === 'View setting') {
@@ -235,3 +265,37 @@ export async function notifyMissingManagerIfDefault(
             });
     }
 }
+
+/**
+ * Removes the first occurrence of 'defaultEnvManager' set to managerId, returns where it was removed, and logs the action.
+ * @param managerId The manager id to match and remove.
+ * @returns { found: boolean, scope?: string }
+ */
+export async function removeFirstDefaultEnvManagerSettingDetailed(
+    managerId: string,
+): Promise<{ found: boolean; scope?: string }> {
+    const config = workspace.getConfiguration('python-envs');
+    const inspect = config.inspect('defaultEnvManager');
+
+    // Workspace folder settings (multi-root)
+    if (inspect?.workspaceFolderValue !== undefined && inspect.workspaceFolderValue === managerId) {
+        await config.update('defaultEnvManager', undefined, ConfigurationTarget.WorkspaceFolder);
+        traceLog("[python-envs] Removed 'defaultEnvManager' from Workspace Folder settings.");
+        return { found: true, scope: 'Workspace Folder' };
+    }
+    // Workspace settings
+    if (inspect?.workspaceValue !== undefined && inspect.workspaceValue === managerId) {
+        await config.update('defaultEnvManager', undefined, ConfigurationTarget.Workspace);
+        traceLog("[python-envs] Removed 'defaultEnvManager' from Workspace settings.");
+        return { found: true, scope: 'Workspace' };
+    }
+    // User/global settings
+    if (inspect?.globalValue !== undefined && inspect.globalValue === managerId) {
+        await config.update('defaultEnvManager', undefined, ConfigurationTarget.Global);
+        traceLog("[python-envs] Removed 'defaultEnvManager' from User/Global settings.");
+        return { found: true, scope: 'User/Global' };
+    }
+    // No matching setting found
+    traceVerbose(`[python-envs] Could not find 'defaultEnvManager' set to '${managerId}' in any scope.`);
+    return { found: false };
+}