Skip directory .env / python.envFile paths when resolving environment variables (#1865)

If `<project>/.env` was a directory, for example a virtual environment
named `.env`, `getEnvironmentVariables()` tried to read it as a file and
threw `EntryIsADirectory`. That broke terminal env injection and
Pylance. The same happened when `python.envFile` pointed at a directory.
The cause was the `fs-extra` `pathExists` check, which also returns true
for directories.

### Changes

- **`envVariableManager.ts`**: both `pathExists` checks are replaced
with a private `isEnvFile` helper, which accepts only regular files:
  ```ts
  async function isEnvFile(filePath: string): Promise<boolean> {
      try {
          return (await fsapi.stat(filePath)).isFile();
      } catch (error) {
          const code = (error as NodeJS.ErrnoException).code;
          if (code === 'ENOENT' || code === 'ENOTDIR') {
              return false;
          }
          throw error;
      }
  }
  ```
- It uses `stat`, not `lstat`, so symlinks to regular files still load.
Symlinks to directories are skipped.
- Errors other than `ENOENT`/`ENOTDIR` (for example, `EACCES`) are still
raised, not hidden.
  - `parseEnvFile` is never called on a skipped path.
- **Tests** (`envVariableManager.unit.test.ts`): these call
`getEnvironmentVariables` directly and cover:
  - a directory at either path
  - a valid file next to a directory
  - two regular files loading in the existing order
- symlinks to a file or a directory, using real temp-dir symlinks that
are skipped if the platform can't create them
  - missing paths and `ENOTDIR` being skipped, and `EACCES` being raised

### Not changed

- **Precedence:** the order documented in `docs/README.md` stays the
same: base → `python.envFile` → project `.env` → overrides. This PR does
**not** implement the issue's separate request to have `python.envFile`
suppress project `.env` discovery.
- **Other behavior:** path selection, deduplication, merging, and URI
overrides are untouched.
- **Race:** this is a check before the read, so a path that changes type
between the `stat` and the read can still fail.

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: edvilme <5952839+edvilme@users.noreply.github.com>
Co-authored-by: Eduardo Villalpando Mello <eduardovil@microsoft.com>

Author: Copilot

src/features/execution/envVariableManager.ts

@@ -8,6 +8,23 @@ import { createFileSystemWatcher, getConfiguration } from '../../common/workspac
 import type { PythonProjectManager } from '../projectManager';
 import { mergeEnvVariables, parseEnvFile } from './envVarUtils';
 
+/**
+ * Returns true if the path resolves (following symlinks) to a regular file.
+ * Missing paths and paths with a non-directory parent are treated as absent;
+ * other errors (for example, permission errors) are propagated.
+ */
+async function isEnvFile(filePath: string): Promise<boolean> {
+    try {
+        return (await fsapi.stat(filePath)).isFile();
+    } catch (error) {
+        const code = (error as NodeJS.ErrnoException).code;
+        if (code === 'ENOENT' || code === 'ENOTDIR') {
+            return false;
+        }
+        throw error;
+    }
+}
+
 export interface EnvVarManager extends PythonEnvironmentVariablesApi, Disposable {}
 
 export class PythonEnvVariableManager implements EnvVarManager {
@@ -50,7 +67,7 @@ export class PythonEnvVariableManager implements EnvVarManager {
         let envFilePath = config.get<string>('envFile');
         envFilePath = envFilePath ? path.normalize(resolveVariables(envFilePath, uri)) : undefined;
 
-        if (envFilePath && (await fsapi.pathExists(envFilePath))) {
+        if (envFilePath && (await isEnvFile(envFilePath))) {
             const other = await parseEnvFile(Uri.file(envFilePath));
             env = mergeEnvVariables(env, other);
         }
@@ -59,7 +76,7 @@ export class PythonEnvVariableManager implements EnvVarManager {
         if (
             projectEnvFilePath &&
             projectEnvFilePath?.toLowerCase() !== envFilePath?.toLowerCase() &&
-            (await fsapi.pathExists(projectEnvFilePath))
+            (await isEnvFile(projectEnvFilePath))
         ) {
             const other = await parseEnvFile(Uri.file(projectEnvFilePath));
             env = mergeEnvVariables(env, other);

src/test/features/execution/envVariableManager.unit.test.ts

@@ -0,0 +1,217 @@
+import * as assert from 'assert';
+import fsapi from 'fs-extra';
+import * as os from 'os';
+import * as path from 'path';
+import * as sinon from 'sinon';
+import { Uri } from 'vscode';
+import * as workspaceApis from '../../../common/workspace.apis';
+import * as envVarUtils from '../../../features/execution/envVarUtils';
+import { PythonEnvVariableManager } from '../../../features/execution/envVariableManager';
+import type { PythonProjectManager } from '../../../features/projectManager';
+
+type StatResult = 'file' | 'directory' | NodeJS.ErrnoException;
+
+function errnoError(code: string): NodeJS.ErrnoException {
+    const error = new Error(code) as NodeJS.ErrnoException;
+    error.code = code;
+    return error;
+}
+
+function pathKey(filePath: string): string {
+    const normalizedPath = path.normalize(filePath);
+    return process.platform === 'win32' ? normalizedPath.toLowerCase() : normalizedPath;
+}
+
+suite('PythonEnvVariableManager.getEnvironmentVariables', () => {
+    let sandbox: sinon.SinonSandbox;
+    let parseEnvFileStub: sinon.SinonStub;
+    let configuredEnvFile: string | undefined;
+    let manager: PythonEnvVariableManager;
+
+    const projectRoot = path.resolve('/workspace/project');
+    const projectUri = Uri.file(projectRoot);
+    const projectEnvFile = path.normalize(path.join(projectRoot, '.env'));
+    const configuredFile = path.normalize(path.resolve('/config/custom.env'));
+
+    function parsedPaths(): string[] {
+        return parseEnvFileStub.getCalls().map((c) => pathKey((c.args[0] as Uri).fsPath));
+    }
+
+    function stubStat(results: Map<string, StatResult>): void {
+        const normalizedResults = new Map([...results].map(([p, result]) => [pathKey(p), result]));
+        sandbox.stub(fsapi, 'stat').callsFake((async (p: string) => {
+            const result = normalizedResults.get(pathKey(p)) ?? errnoError('ENOENT');
+            if (result === 'file' || result === 'directory') {
+                return { isFile: () => result === 'file' } as fsapi.Stats;
+            }
+            throw result;
+        }) as unknown as typeof fsapi.stat);
+    }
+
+    setup(() => {
+        sandbox = sinon.createSandbox();
+        configuredEnvFile = undefined;
+
+        const mockWatcher = {
+            onDidCreate: () => ({ dispose: () => {} }),
+            onDidChange: () => ({ dispose: () => {} }),
+            onDidDelete: () => ({ dispose: () => {} }),
+            dispose: () => {},
+        };
+        sandbox.stub(workspaceApis, 'createFileSystemWatcher').returns(mockWatcher as never);
+        sandbox.stub(workspaceApis, 'getWorkspaceFolder').returns(undefined);
+        sandbox.stub(workspaceApis, 'getWorkspaceFolders').returns(undefined);
+        sandbox.stub(workspaceApis, 'getConfiguration').returns({
+            get: (key: string) => (key === 'envFile' ? configuredEnvFile : undefined),
+        } as never);
+
+        parseEnvFileStub = sandbox.stub(envVarUtils, 'parseEnvFile');
+        parseEnvFileStub.callsFake(async (uri: Uri) => {
+            if (pathKey(uri.fsPath) === pathKey(projectEnvFile)) {
+                return { PROJECT_VAR: 'project', SHARED: 'from-project' };
+            }
+            return { CONFIG_VAR: 'config', SHARED: 'from-config' };
+        });
+
+        const pm = {
+            get: () => ({ name: 'project', uri: projectUri }),
+        } as unknown as PythonProjectManager;
+        manager = new PythonEnvVariableManager(pm);
+    });
+
+    teardown(() => {
+        manager.dispose();
+        sandbox.restore();
+    });
+
+    test('project .env directory with missing configured file does not throw and leaves base unchanged', async () => {
+        configuredEnvFile = configuredFile;
+        stubStat(new Map<string, StatResult>([[projectEnvFile, 'directory']]));
+        const base = { BASE: 'base' };
+
+        const env = await manager.getEnvironmentVariables(projectUri, undefined, base);
+
+        assert.deepStrictEqual(env, { BASE: 'base' });
+        assert.deepStrictEqual(parsedPaths(), []);
+    });
+
+    test('configured env file that is a directory is skipped while project .env still loads', async () => {
+        configuredEnvFile = configuredFile;
+        stubStat(
+            new Map<string, StatResult>([
+                [configuredFile, 'directory'],
+                [projectEnvFile, 'file'],
+            ]),
+        );
+
+        const env = await manager.getEnvironmentVariables(projectUri, undefined, { BASE: 'base' });
+
+        assert.deepStrictEqual(parsedPaths(), [pathKey(projectEnvFile)]);
+        assert.strictEqual(env.PROJECT_VAR, 'project');
+        assert.strictEqual(env.CONFIG_VAR, undefined);
+    });
+
+    test('valid configured file is loaded when project .env is a directory', async () => {
+        configuredEnvFile = configuredFile;
+        stubStat(
+            new Map<string, StatResult>([
+                [configuredFile, 'file'],
+                [projectEnvFile, 'directory'],
+            ]),
+        );
+
+        const env = await manager.getEnvironmentVariables(projectUri, undefined, { BASE: 'base' });
+
+        assert.deepStrictEqual(parsedPaths(), [pathKey(configuredFile)]);
+        assert.strictEqual(env.CONFIG_VAR, 'config');
+        assert.strictEqual(env.SHARED, 'from-config');
+    });
+
+    test('when both are regular files, configured file is applied before project .env', async () => {
+        configuredEnvFile = configuredFile;
+        stubStat(
+            new Map<string, StatResult>([
+                [configuredFile, 'file'],
+                [projectEnvFile, 'file'],
+            ]),
+        );
+
+        const env = await manager.getEnvironmentVariables(projectUri, undefined, { BASE: 'base' });
+
+        assert.deepStrictEqual(parsedPaths(), [pathKey(configuredFile), pathKey(projectEnvFile)]);
+        assert.strictEqual(env.SHARED, 'from-project');
+        assert.strictEqual(env.PROJECT_VAR, 'project');
+    });
+
+    test('missing paths and ENOTDIR are skipped without parsing', async () => {
+        configuredEnvFile = configuredFile;
+        stubStat(new Map<string, StatResult>([[configuredFile, errnoError('ENOTDIR')]]));
+        const base = { BASE: 'base' };
+
+        const env = await manager.getEnvironmentVariables(projectUri, undefined, base);
+
+        assert.deepStrictEqual(env, { BASE: 'base' });
+        assert.deepStrictEqual(parsedPaths(), []);
+    });
+
+    test('unexpected stat errors such as EACCES are propagated', async () => {
+        stubStat(new Map<string, StatResult>([[projectEnvFile, errnoError('EACCES')]]));
+
+        await assert.rejects(
+            manager.getEnvironmentVariables(projectUri, undefined, { BASE: 'base' }),
+            (err: NodeJS.ErrnoException) => err.code === 'EACCES',
+        );
+        assert.deepStrictEqual(parsedPaths(), []);
+    });
+
+    suite('symlinks', () => {
+        let tmpDir: string;
+
+        setup(async () => {
+            tmpDir = await fsapi.mkdtemp(path.join(os.tmpdir(), 'envvarmgr-'));
+        });
+
+        teardown(async () => {
+            await fsapi.remove(tmpDir);
+        });
+
+        async function trySymlink(target: string, link: string, type: 'file' | 'dir'): Promise<boolean> {
+            try {
+                await fsapi.symlink(target, link, type);
+                return true;
+            } catch {
+                return false;
+            }
+        }
+
+        test('symlink to a regular file is accepted', async function () {
+            const target = path.join(tmpDir, 'real.env');
+            const link = path.join(tmpDir, 'link.env');
+            await fsapi.writeFile(target, 'CONFIG_VAR=config\n');
+            if (!(await trySymlink(target, link, 'file'))) {
+                this.skip();
+            }
+            configuredEnvFile = link;
+
+            const env = await manager.getEnvironmentVariables(projectUri, undefined, { BASE: 'base' });
+
+            assert.deepStrictEqual(parsedPaths(), [pathKey(link)]);
+            assert.strictEqual(env.CONFIG_VAR, 'config');
+        });
+
+        test('symlink to a directory is skipped', async function () {
+            const target = path.join(tmpDir, 'realdir');
+            const link = path.join(tmpDir, 'linkdir');
+            await fsapi.mkdir(target);
+            if (!(await trySymlink(target, link, 'dir'))) {
+                this.skip();
+            }
+            configuredEnvFile = link;
+
+            const env = await manager.getEnvironmentVariables(projectUri, undefined, { BASE: 'base' });
+
+            assert.deepStrictEqual(env, { BASE: 'base' });
+            assert.deepStrictEqual(parsedPaths(), []);
+        });
+    });
+});