feat: add disambiguation suffixes for Python environments in env manager

Author: eleanorjboyd

src/features/views/envManagersView.ts

@@ -17,6 +17,7 @@ import {
     EnvManagerTreeItem,
     EnvTreeItem,
     EnvTreeItemKind,
+    getEnvironmentParentDirName,
     NoPythonEnvTreeItem,
     PackageTreeItem,
     PythonEnvTreeItem,
@@ -27,6 +28,53 @@ const COPIED_STATE = 'copied';
 const SELECTED_STATE = 'selected';
 const ENV_STATE_KEYS = [COPIED_STATE, SELECTED_STATE];
 
+/**
+ * Extracts the base name from a display name by removing version info.
+ * @example getBaseName('.venv (3.12)') returns '.venv'
+ * @example getBaseName('myenv (3.14.1)') returns 'myenv'
+ */
+function getBaseName(displayName: string): string {
+    return displayName.replace(/\s*\([0-9.]+\)\s*$/, '').trim();
+}
+
+/**
+ * Computes disambiguation suffixes for environments with similar base names.
+ *
+ * When multiple environments share the same base name (ignoring version numbers),
+ * this function returns a map from environment ID to the parent folder name,
+ * which can be displayed to help users distinguish between them.
+ *
+ * @example Two environments '.venv (3.12)' in folders 'alice' and 'bob' would
+ * return suffixes 'alice' and 'bob' respectively.
+ *
+ * @param envs List of environments to analyze
+ * @returns Map from environment ID to disambiguation suffix (parent folder name)
+ */
+function computeDisambiguationSuffixes(envs: PythonEnvironment[]): Map<string, string> {
+    const suffixes = new Map<string, string>();
+
+    // Group environments by their base name (ignoring version)
+    const baseNameToEnvs = new Map<string, PythonEnvironment[]>();
+    for (const env of envs) {
+        const displayName = env.displayName ?? env.name;
+        const baseName = getBaseName(displayName);
+        const existing = baseNameToEnvs.get(baseName) ?? [];
+        existing.push(env);
+        baseNameToEnvs.set(baseName, existing);
+    }
+
+    // For base names with multiple environments, compute suffixes
+    for (const [, similarEnvs] of baseNameToEnvs) {
+        if (similarEnvs.length > 1) {
+            for (const env of similarEnvs) {
+                suffixes.set(env.envId.id, getEnvironmentParentDirName(env));
+            }
+        }
+    }
+
+    return suffixes;
+}
+
 export class EnvManagerView implements TreeDataProvider<EnvTreeItem>, Disposable {
     private treeView: TreeView<EnvTreeItem>;
     private treeDataChanged: EventEmitter<EnvTreeItem | EnvTreeItem[] | null | undefined> = new EventEmitter<
@@ -37,7 +85,10 @@ export class EnvManagerView implements TreeDataProvider<EnvTreeItem>, Disposable
     private selected: Map<string, string> = new Map();
     private disposables: Disposable[] = [];
 
-    public constructor(public providers: EnvironmentManagers, private stateManager: ITemporaryStateManager) {
+    public constructor(
+        public providers: EnvironmentManagers,
+        private stateManager: ITemporaryStateManager,
+    ) {
         this.treeView = window.createTreeView<EnvTreeItem>('env-managers', {
             treeDataProvider: this,
         });
@@ -119,8 +170,16 @@ export class EnvManagerView implements TreeDataProvider<EnvTreeItem>, Disposable
             const manager = (element as EnvManagerTreeItem).manager;
             const views: EnvTreeItem[] = [];
             const envs = await manager.getEnvironments('all');
-            envs.filter((e) => !e.group).forEach((env) => {
-                const view = new PythonEnvTreeItem(env, element as EnvManagerTreeItem, this.selected.get(env.envId.id));
+            const nonGroupedEnvs = envs.filter((e) => !e.group);
+            const disambiguationSuffixes = computeDisambiguationSuffixes(nonGroupedEnvs);
+            nonGroupedEnvs.forEach((env) => {
+                const suffix = disambiguationSuffixes.get(env.envId.id);
+                const view = new PythonEnvTreeItem(
+                    env,
+                    element as EnvManagerTreeItem,
+                    this.selected.get(env.envId.id),
+                    suffix,
+                );
                 views.push(view);
                 this.revealMap.set(env.envId.id, view);
             });
@@ -162,8 +221,10 @@ export class EnvManagerView implements TreeDataProvider<EnvTreeItem>, Disposable
                 return false;
             });
 
+            const groupDisambiguationSuffixes = computeDisambiguationSuffixes(grouped);
             grouped.forEach((env) => {
-                const view = new PythonEnvTreeItem(env, groupItem, this.selected.get(env.envId.id));
+                const suffix = groupDisambiguationSuffixes.get(env.envId.id);
+                const view = new PythonEnvTreeItem(env, groupItem, this.selected.get(env.envId.id), suffix);
                 views.push(view);
                 this.revealMap.set(env.envId.id, view);
             });

src/features/views/treeViewItems.ts

@@ -5,6 +5,43 @@ import { InternalEnvironmentManager, InternalPackageManager } from '../../intern
 import { isActivatableEnvironment } from '../common/activation';
 import { removable } from './utils';
 
+/**
+ * Extracts the parent folder name from an environment path for disambiguation.
+ *
+ * This function handles various path formats including:
+ * - Unix paths with bin folder: /home/user/my-project/.venv/bin/python → my-project
+ * - Windows paths with Scripts folder: C:\Users\bob\project\.venv\Scripts\python.exe → project
+ * - Direct venv folder paths: /home/user/project/.venv → project
+ *
+ * @param environment The Python environment to extract the parent folder from
+ * @returns The name of the parent folder containing the virtual environment
+ */
+export function getEnvironmentParentDirName(environment: PythonEnvironment): string {
+    const envPath = environment.environmentPath.fsPath.replace(/\\/g, '/');
+    const parts = envPath.split('/').filter((p) => p.length > 0);
+
+    let venvFolderIndex = -1;
+
+    for (let i = parts.length - 1; i >= 0; i--) {
+        const part = parts[i].toLowerCase();
+        if (part === 'bin' || part === 'scripts') {
+            venvFolderIndex = i - 1;
+            break;
+        }
+        if (part.startsWith('python')) {
+            continue;
+        }
+        venvFolderIndex = i;
+        break;
+    }
+
+    if (venvFolderIndex > 0) {
+        return parts[venvFolderIndex - 1];
+    }
+
+    return parts.length >= 2 ? parts[parts.length - 2] : parts[0] || '';
+}
+
 export enum EnvTreeItemKind {
     manager = 'python-env-manager',
     environment = 'python-env',
@@ -45,7 +82,10 @@ export class EnvManagerTreeItem implements EnvTreeItem {
 export class PythonGroupEnvTreeItem implements EnvTreeItem {
     public readonly kind = EnvTreeItemKind.environmentGroup;
     public readonly treeItem: TreeItem;
-    constructor(public readonly parent: EnvManagerTreeItem, public readonly group: string | EnvironmentGroupInfo) {
+    constructor(
+        public readonly parent: EnvManagerTreeItem,
+        public readonly group: string | EnvironmentGroupInfo,
+    ) {
         const label = typeof group === 'string' ? group : group.name;
         const item = new TreeItem(label, TreeItemCollapsibleState.Collapsed);
         item.contextValue = `pythonEnvGroup;${this.parent.manager.id}:${label};`;
@@ -62,12 +102,21 @@ export class PythonGroupEnvTreeItem implements EnvTreeItem {
 export class PythonEnvTreeItem implements EnvTreeItem {
     public readonly kind = EnvTreeItemKind.environment;
     public readonly treeItem: TreeItem;
+    /**
+     * Creates a tree item for a Python environment.
+     * @param environment The Python environment to display
+     * @param parent The parent tree item (manager or group)
+     * @param selected If set, indicates this environment is selected ('global' or workspace path)
+     * @param disambiguationSuffix If set, shown in description to distinguish similarly-named environments
+     */
     constructor(
         public readonly environment: PythonEnvironment,
         public readonly parent: EnvManagerTreeItem | PythonGroupEnvTreeItem,
         public readonly selected?: string,
+        public readonly disambiguationSuffix?: string,
     ) {
-        let name = environment.displayName ?? environment.name;
+        const name = environment.displayName ?? environment.name;
+
         let tooltip = environment.tooltip ?? environment.description;
         if (selected) {
             const selectedTooltip =
@@ -77,7 +126,18 @@ export class PythonEnvTreeItem implements EnvTreeItem {
 
         const item = new TreeItem(name, TreeItemCollapsibleState.Collapsed);
         item.contextValue = this.getContextValue();
-        item.description = environment.description;
+
+        // Build description with optional [uv] indicator and disambiguation suffix
+        const uvIndicator = environment.description?.toLowerCase().includes('uv') ? '[uv]' : '';
+        const descriptionParts: string[] = [];
+        if (uvIndicator) {
+            descriptionParts.push(uvIndicator);
+        }
+        if (disambiguationSuffix) {
+            descriptionParts.push(disambiguationSuffix);
+        }
+        item.description = descriptionParts.length > 0 ? descriptionParts.join(' ') : undefined;
+
         item.tooltip = tooltip;
         item.iconPath = environment.iconPath;
         this.treeItem = item;
@@ -240,7 +300,10 @@ export class ProjectEnvironment implements ProjectTreeItem {
     public readonly kind = ProjectTreeItemKind.environment;
     public readonly id: string;
     public readonly treeItem: TreeItem;
-    constructor(public readonly parent: ProjectItem, public readonly environment: PythonEnvironment) {
+    constructor(
+        public readonly parent: ProjectItem,
+        public readonly environment: PythonEnvironment,
+    ) {
         this.id = this.getId(parent, environment);
         const item = new TreeItem(
             this.environment.displayName ?? this.environment.name,