Fix ${workspaceFolder} resolution and relative path handling for defaultInterpreterPath (#1603)

Fixes #1586

`python.defaultInterpreterPath` failed to resolve in two cases:
`${workspaceFolder}` was left unexpanded when VS Code couldn't determine
the owning folder (e.g. Windows drive-letter casing), and relative paths
were resolved against an unrelated CWD by the native finder—producing
malformed, duplicated paths like
`<workspace>/<workspace-name>/.venv/...`.

### Changes
- **`internalVariables.ts`** — When `getWorkspaceFolder()` returns
`undefined` for a project scope, fall back to the single open workspace
folder so `${workspaceFolder}` still expands.
- **`interpreterSelection.ts`** — Added `toAbsoluteInterpreterPath()` to
resolve relative interpreter paths against the workspace folder (with
the same single-folder fallback) before handing them to the native
finder. Absolute paths pass through unchanged.
- **Tests** — Added unit coverage for the new edge cases:
- `${workspaceFolder}` single-folder fallback, multi-folder no-op,
no-scope, and no-folders-open cases.
- Relative path resolution via owning folder and via single-folder
fallback, multi-folder pass-through, and absolute-path pass-through.

### Notes
- `resolveVariables()` is separator-preserving string substitution, so
the new assertions intentionally compare forward-slash inputs rather
than `path.join()`. Relative-path expectations use `path.resolve()` /
`Uri.file().fsPath` to stay cross-platform.

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: Eduardo Villalpando Mello <eduardovil@microsoft.com>
Copilot-Session: 9ad4171d-6839-4aec-93b4-c6bca21b7329

Author: Copilot

src/common/utils/internalVariables.ts

@@ -12,7 +12,18 @@ export function resolveVariables(value: string, project?: Uri, env?: { [key: str
         substitutions.set('${pythonProject}', project.fsPath);
     }
 
-    const workspace = project ? getWorkspaceFolder(project) : undefined;
+    // Resolve ${workspaceFolder} for a project (workspace) scope. Prefer the workspace folder
+    // that owns the project URI, but fall back to the single open workspace folder when the
+    // owning folder can't be determined (e.g. drive-letter casing differences on Windows can
+    // cause workspace.getWorkspaceFolder() to return undefined). Without this fallback the
+    // ${workspaceFolder} token would be left unexpanded and downstream path resolution fails.
+    let workspace = project ? getWorkspaceFolder(project) : undefined;
+    if (!workspace && project) {
+        const folders = getWorkspaceFolders();
+        if (folders && folders.length === 1) {
+            workspace = folders[0];
+        }
+    }
     if (workspace) {
         substitutions.set('${workspaceFolder}', workspace.uri.fsPath);
     }

src/features/interpreterSelection.ts

@@ -132,38 +132,24 @@ async function resolvePriorityChainCore(
                 );
             }
         } else {
-            const expandedInterpreterPath = resolveVariables(userInterpreterPath, scope);
-            if (expandedInterpreterPath.includes('${')) {
-                traceWarn(
-                    `${logPrefix} defaultInterpreterPath '${userInterpreterPath}' contains unresolved variables, falling back to auto-discovery`,
-                );
-                const error: SettingResolutionError = {
-                    setting: 'defaultInterpreterPath',
-                    kind: 'pathUnresolvedVariables',
-                    configuredValue: userInterpreterPath,
-                };
-                errors.push(error);
-            } else {
-                const resolved = await tryResolveInterpreterPath(
-                    nativeFinder,
-                    api,
-                    expandedInterpreterPath,
-                    envManagers,
-                );
-                if (resolved) {
-                    traceVerbose(`${logPrefix} Priority 3: Using defaultInterpreterPath: ${userInterpreterPath}`);
-                    return { result: resolved, errors };
-                }
-                const error: SettingResolutionError = {
-                    setting: 'defaultInterpreterPath',
-                    kind: 'pathCannotResolve',
-                    configuredValue: userInterpreterPath,
-                };
-                errors.push(error);
-                traceWarn(
-                    `${logPrefix} defaultInterpreterPath '${userInterpreterPath}' unresolvable, falling back to auto-discovery`,
-                );
+            // Resolve relative paths against the workspace folder so the native finder doesn't
+            // resolve them against an unrelated current working directory (which can produce a
+            // malformed, duplicated path such as <workspace>/<workspace-name>/.venv/...).
+            const absoluteInterpreterPath = toAbsoluteInterpreterPath(expandedInterpreterPath, scope);
+            const resolved = await tryResolveInterpreterPath(nativeFinder, api, absoluteInterpreterPath, envManagers);
+            if (resolved) {
+                traceVerbose(`${logPrefix} Priority 3: Using defaultInterpreterPath: ${userInterpreterPath}`);
+                return { result: resolved, errors };
             }
+            const error: SettingResolutionError = {
+                setting: 'defaultInterpreterPath',
+                kind: 'pathCannotResolve',
+                configuredValue: userInterpreterPath,
+            };
+            errors.push(error);
+            traceWarn(
+                `${logPrefix} defaultInterpreterPath '${userInterpreterPath}' unresolvable, falling back to auto-discovery`,
+            );
         }
     }
 
@@ -545,6 +531,27 @@ function getProjectSpecificEnvManager(projectManager: PythonProjectManager, scop
     return undefined;
 }
 
+/**
+ * Resolve a (variable-expanded) interpreter path to an absolute path.
+ *
+ * `python.defaultInterpreterPath` may be configured as a relative path (e.g. `.venv/bin/python`).
+ * The native finder resolves relative paths against its own working directory, which is unrelated
+ * to the workspace and can produce malformed paths (including a duplicated workspace segment).
+ * To avoid this, relative paths are resolved against the workspace folder identified by the scope.
+ * Global relative paths are left unchanged because there is no workspace context to resolve against.
+ *
+ * @param interpreterPath - The interpreter path after variable substitution.
+ * @param scope - The workspace folder URI, or undefined for global scope.
+ * @returns An absolute interpreter path when possible, otherwise the input unchanged.
+ */
+function toAbsoluteInterpreterPath(interpreterPath: string, scope: Uri | undefined): string {
+    if (path.isAbsolute(interpreterPath) || !scope) {
+        return interpreterPath;
+    }
+    const workspaceFolder = getWorkspaceFolder(scope);
+    return path.resolve(workspaceFolder?.uri.fsPath ?? scope.fsPath, interpreterPath);
+}
+
 /**
  * Try to resolve an interpreter path via nativeFinder and return a PriorityChainResult.
  * Returns undefined if resolution fails.

src/test/common/internalVariables.unit.test.ts

@@ -42,4 +42,48 @@ suite('Internal Variable substitution', () => {
             assert.equal(result, `Some ${item.substitution} text ${item.substitution}`);
         });
     });
+
+    test('Resolve ${workspaceFolder} via single-folder fallback when owning folder is undefined', () => {
+        // Simulates the Windows scenario where workspace.getWorkspaceFolder() fails to find the
+        // owning folder (e.g. drive-letter casing). With a single open folder, the token should
+        // still resolve instead of being left as a literal ${workspaceFolder}.
+        getWorkspaceFolderStub.returns(undefined);
+        getWorkspaceFoldersStub.returns([workspaceFolder]);
+
+        const result = resolveVariables('${workspaceFolder}/.venv/Scripts/python.exe', project.uri as unknown as Uri);
+
+        assert.equal(result, `${workspaceFolder.uri.fsPath}/.venv/Scripts/python.exe`);
+        assert.ok(!result.includes('${workspaceFolder}'), 'token should be expanded');
+    });
+
+    test('Leaves ${workspaceFolder} unresolved when no project scope is provided', () => {
+        // Global scope (no project) must not resolve workspace-specific variables.
+        getWorkspaceFolderStub.returns(undefined);
+        getWorkspaceFoldersStub.returns([workspaceFolder]);
+
+        const result = resolveVariables('${workspaceFolder}/.venv/Scripts/python.exe');
+
+        assert.equal(result, '${workspaceFolder}/.venv/Scripts/python.exe');
+    });
+
+    test('Does not use single-folder fallback for ${workspaceFolder} with multiple folders', () => {
+        const otherFolder = { name: 'workspace2', uri: { fsPath: path.join(home, 'workspace2') } };
+        getWorkspaceFolderStub.returns(undefined);
+        getWorkspaceFoldersStub.returns([workspaceFolder, otherFolder]);
+
+        const result = resolveVariables('${workspaceFolder}/.venv/Scripts/python.exe', project.uri as unknown as Uri);
+
+        assert.equal(result, '${workspaceFolder}/.venv/Scripts/python.exe');
+    });
+
+    test('Leaves ${workspaceFolder} unresolved when no folders are open', () => {
+        // No owning folder and no open folders at all (getWorkspaceFolders returns undefined):
+        // the single-folder fallback must not crash and the token stays literal.
+        getWorkspaceFolderStub.returns(undefined);
+        getWorkspaceFoldersStub.returns(undefined);
+
+        const result = resolveVariables('${workspaceFolder}/.venv/Scripts/python.exe', project.uri as unknown as Uri);
+
+        assert.equal(result, '${workspaceFolder}/.venv/Scripts/python.exe');
+    });
 });

src/test/features/interpreterSelection.unit.test.ts

@@ -268,6 +268,173 @@ suite('Interpreter Selection - Priority Chain', () => {
             assert.ok(mockNativeFinder.resolve.calledOnceWithExactly(expandedInterpreterPath));
         });
 
+        test('should resolve a relative defaultInterpreterPath against the workspace folder', async () => {
+            // A relative path must be made absolute against the workspace folder so the native
+            // finder does not resolve it against an unrelated working directory (which can yield
+            // a malformed, duplicated path such as <workspace>/<workspace-name>/.venv/...).
+            const workspaceUri = Uri.file(path.resolve('/test/workspace'));
+            const absoluteInterpreterPath = path.resolve(workspaceUri.fsPath, '.venv/bin/python');
+            const workspaceFolder = { name: 'workspace', uri: workspaceUri } as WorkspaceFolder;
+
+            sandbox.stub(workspaceApis, 'getConfiguration').returns(createMockConfig([]) as WorkspaceConfiguration);
+            sandbox.stub(workspaceApis, 'getWorkspaceFolder').returns(workspaceFolder);
+            sandbox.stub(workspaceApis, 'getWorkspaceFolders').returns([workspaceFolder]);
+            sandbox.stub(helpers, 'getUserConfiguredSetting').callsFake((section: string, key: string) => {
+                if (section === 'python' && key === 'defaultInterpreterPath') {
+                    return './.venv/bin/python';
+                }
+                return undefined;
+            });
+            mockNativeFinder.resolve.resolves({
+                executable: absoluteInterpreterPath,
+                version: '3.11.0',
+                prefix: path.dirname(path.dirname(absoluteInterpreterPath)),
+            });
+            mockApi.resolveEnvironment.resolves({
+                ...mockVenvEnv,
+                displayPath: absoluteInterpreterPath,
+                environmentPath: Uri.file(absoluteInterpreterPath),
+                execInfo: { run: { executable: absoluteInterpreterPath } },
+            });
+
+            const result = await resolveEnvironmentByPriority(
+                workspaceUri,
+                mockEnvManagers as unknown as EnvironmentManagers,
+                mockProjectManager as unknown as PythonProjectManager,
+                mockNativeFinder as unknown as NativePythonFinder,
+                mockApi as unknown as PythonEnvironmentApi,
+            );
+
+            assert.strictEqual(result.source, 'defaultInterpreterPath');
+            assert.ok(mockNativeFinder.resolve.calledOnceWithExactly(absoluteInterpreterPath));
+            // The path passed to the native finder must not duplicate the workspace folder name.
+            const passedPath = mockNativeFinder.resolve.firstCall.args[0] as string;
+            assert.ok(
+                !passedPath.includes(`workspace${path.sep}workspace`),
+                `path should not duplicate the workspace folder: ${passedPath}`,
+            );
+        });
+
+        test('should resolve a relative defaultInterpreterPath from its scope when folder lookup fails', async () => {
+            // The scope already identifies the workspace folder, so drive-letter casing must not
+            // prevent relative path resolution when getWorkspaceFolder returns undefined.
+            const workspaceUri = Uri.file(path.resolve('/test/workspace'));
+            const absoluteInterpreterPath = path.resolve(workspaceUri.fsPath, '.venv/bin/python');
+            const workspaceFolder = { name: 'workspace', uri: workspaceUri } as WorkspaceFolder;
+
+            sandbox.stub(workspaceApis, 'getConfiguration').returns(createMockConfig([]) as WorkspaceConfiguration);
+            sandbox.stub(workspaceApis, 'getWorkspaceFolder').returns(undefined);
+            sandbox.stub(workspaceApis, 'getWorkspaceFolders').returns([workspaceFolder]);
+            sandbox.stub(helpers, 'getUserConfiguredSetting').callsFake((section: string, key: string) => {
+                if (section === 'python' && key === 'defaultInterpreterPath') {
+                    return './.venv/bin/python';
+                }
+                return undefined;
+            });
+            mockNativeFinder.resolve.resolves({
+                executable: absoluteInterpreterPath,
+                version: '3.11.0',
+                prefix: path.dirname(path.dirname(absoluteInterpreterPath)),
+            });
+            mockApi.resolveEnvironment.resolves({
+                ...mockVenvEnv,
+                displayPath: absoluteInterpreterPath,
+                environmentPath: Uri.file(absoluteInterpreterPath),
+                execInfo: { run: { executable: absoluteInterpreterPath } },
+            });
+
+            const result = await resolveEnvironmentByPriority(
+                workspaceUri,
+                mockEnvManagers as unknown as EnvironmentManagers,
+                mockProjectManager as unknown as PythonProjectManager,
+                mockNativeFinder as unknown as NativePythonFinder,
+                mockApi as unknown as PythonEnvironmentApi,
+            );
+
+            assert.strictEqual(result.source, 'defaultInterpreterPath');
+            assert.ok(mockNativeFinder.resolve.calledOnceWithExactly(absoluteInterpreterPath));
+        });
+
+        test('should resolve a relative defaultInterpreterPath from its scope with multiple folders open', async () => {
+            const workspaceUri = Uri.file(path.resolve('/test/workspace'));
+            const otherUri = Uri.file(path.resolve('/test/other'));
+            const relativeInterpreterPath = './.venv/bin/python';
+            const absoluteInterpreterPath = path.resolve(workspaceUri.fsPath, relativeInterpreterPath);
+
+            sandbox.stub(workspaceApis, 'getConfiguration').returns(createMockConfig([]) as WorkspaceConfiguration);
+            sandbox.stub(workspaceApis, 'getWorkspaceFolder').returns(undefined);
+            sandbox.stub(workspaceApis, 'getWorkspaceFolders').returns([
+                { name: 'workspace', uri: workspaceUri } as WorkspaceFolder,
+                { name: 'other', uri: otherUri } as WorkspaceFolder,
+            ]);
+            sandbox.stub(helpers, 'getUserConfiguredSetting').callsFake((section: string, key: string) => {
+                if (section === 'python' && key === 'defaultInterpreterPath') {
+                    return relativeInterpreterPath;
+                }
+                return undefined;
+            });
+            mockNativeFinder.resolve.resolves({
+                executable: absoluteInterpreterPath,
+                version: '3.11.0',
+                prefix: path.dirname(path.dirname(absoluteInterpreterPath)),
+            });
+            mockApi.resolveEnvironment.resolves({
+                ...mockVenvEnv,
+                displayPath: absoluteInterpreterPath,
+                environmentPath: Uri.file(absoluteInterpreterPath),
+                execInfo: { run: { executable: absoluteInterpreterPath } },
+            });
+
+            await resolveEnvironmentByPriority(
+                workspaceUri,
+                mockEnvManagers as unknown as EnvironmentManagers,
+                mockProjectManager as unknown as PythonProjectManager,
+                mockNativeFinder as unknown as NativePythonFinder,
+                mockApi as unknown as PythonEnvironmentApi,
+            );
+
+            assert.ok(mockNativeFinder.resolve.calledOnceWithExactly(absoluteInterpreterPath));
+        });
+
+        test('should pass an absolute defaultInterpreterPath to the native finder unchanged', async () => {
+            // Absolute paths must not be re-resolved against the workspace folder.
+            const workspaceUri = Uri.file(path.resolve('/test/workspace'));
+            const absoluteInterpreterPath = Uri.file(path.resolve('/opt/python/bin/python')).fsPath;
+            const workspaceFolder = { name: 'workspace', uri: workspaceUri } as WorkspaceFolder;
+
+            sandbox.stub(workspaceApis, 'getConfiguration').returns(createMockConfig([]) as WorkspaceConfiguration);
+            sandbox.stub(workspaceApis, 'getWorkspaceFolder').returns(workspaceFolder);
+            sandbox.stub(workspaceApis, 'getWorkspaceFolders').returns([workspaceFolder]);
+            sandbox.stub(helpers, 'getUserConfiguredSetting').callsFake((section: string, key: string) => {
+                if (section === 'python' && key === 'defaultInterpreterPath') {
+                    return absoluteInterpreterPath;
+                }
+                return undefined;
+            });
+            mockNativeFinder.resolve.resolves({
+                executable: absoluteInterpreterPath,
+                version: '3.11.0',
+                prefix: path.dirname(path.dirname(absoluteInterpreterPath)),
+            });
+            mockApi.resolveEnvironment.resolves({
+                ...mockSystemEnv,
+                displayPath: absoluteInterpreterPath,
+                environmentPath: Uri.file(absoluteInterpreterPath),
+                execInfo: { run: { executable: absoluteInterpreterPath } },
+            });
+
+            const result = await resolveEnvironmentByPriority(
+                workspaceUri,
+                mockEnvManagers as unknown as EnvironmentManagers,
+                mockProjectManager as unknown as PythonProjectManager,
+                mockNativeFinder as unknown as NativePythonFinder,
+                mockApi as unknown as PythonEnvironmentApi,
+            );
+
+            assert.strictEqual(result.source, 'defaultInterpreterPath');
+            assert.ok(mockNativeFinder.resolve.calledOnceWithExactly(absoluteInterpreterPath));
+        });
+
         test('should skip native resolution when defaultInterpreterPath has unresolved variables', async () => {
             // When resolveVariables can't resolve ${workspaceFolder} (e.g., global scope with no workspace),
             // the path still contains '${' and should be skipped without calling nativeFinder.resolve
@@ -1183,6 +1350,36 @@ suite('Interpreter Selection - resolveGlobalEnvironmentByPriority', () => {
         assert.strictEqual(result.environment.execInfo?.run?.executable, userPyenvPath);
     });
 
+    test('should not resolve a global relative defaultInterpreterPath against the open workspace', async () => {
+        const relativeInterpreterPath = path.join('.venv', process.platform === 'win32' ? 'Scripts' : 'bin', 'python');
+        const workspaceFolder = {
+            name: 'workspace',
+            uri: Uri.file(path.resolve('/test/workspace')),
+        } as WorkspaceFolder;
+
+        sandbox.stub(workspaceApis, 'getWorkspaceFolders').returns([workspaceFolder]);
+        sandbox.stub(helpers, 'getUserConfiguredSetting').callsFake((section: string, key: string) => {
+            if (section === 'python' && key === 'defaultInterpreterPath') {
+                return relativeInterpreterPath;
+            }
+            return undefined;
+        });
+        mockNativeFinder.resolve.resolves({
+            executable: relativeInterpreterPath,
+            version: '3.11.0',
+            prefix: '.venv',
+        });
+        mockApi.resolveEnvironment.resolves(mockSystemEnv);
+
+        await resolveGlobalEnvironmentByPriority(
+            mockEnvManagers as unknown as EnvironmentManagers,
+            mockNativeFinder as unknown as NativePythonFinder,
+            mockApi as unknown as PythonEnvironmentApi,
+        );
+
+        assert.ok(mockNativeFinder.resolve.calledOnceWithExactly(relativeInterpreterPath));
+    });
+
     test('should use original user path for global scope even when nativeFinder resolves to different executable', async () => {
         // This is the key bug fix test - user configures pyenv path, native finder returns homebrew
         const userPyenvPath = '/Users/test/.pyenv/versions/3.13.7/bin/python';