fix: fail gracefully on invalid pyproject.toml (Fixes #411) (#1942)

## Summary

- preserve `pyproject.toml` read and parse failures instead of treating
malformed files as empty
- validate the project, build-system, dependency container, and
optional-extra fields consumed during installation
- preflight only the exact dependency files selected by configurable
creation while Quick Create validates relevant workspace dependencies
- apply validation-independent preferred-root eligibility before
duplicate selection so sibling worktrees cannot block or replace the
owning project
- preserve exact owner/ancestor precedence even when malformed metadata
cannot yet emit install arguments
- stop before environment creation on Open, Cancel, or dismissal;
Continue Anyway uses only the filtered owning installables

## Validation

- `npm run lint`
- `npm run compile-tests`
- `npm run compile`
- `npm run unittest` — 3,334 passing, 9 pending
- focused pyproject/creation suite — 179 passing
- VS Code smoke tests — 31 passing, 1 pending
- VS Code E2E tests — 4 passing
- disposable VS Code integration workflows — syntax errors, schema
errors, invalid extras, sibling worktrees in both directions, no `.venv`
on rejection, and valid creation/removal all passed
- broad integration suite — 60 passing, 8 pending; the existing
system-manager creation fixture timed out waiting for interactive Python
installation
- final Copilot review — approval recommended, no open issues

Fixes #411

---------

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 34d0c32e-e8b7-4711-a695-1b6f6e56503f

Author: StellaHuang95

src/managers/builtin/pipUtils.ts

@@ -351,8 +351,9 @@ export async function createStepBasedVenvFlow(
                 allPackages.push(...options.additionalPackages);
             }
 
-            const validationError = result.validationError;
-            const shouldProceed = await shouldProceedAfterPyprojectValidation(validationError, allPackages);
+            const shouldProceed = await shouldProceedAfterPyprojectValidation(result.validationErrors, {
+                allPyprojectTomlsSelected: true,
+            });
             if (!shouldProceed) {
                 return undefined;
             }

src/managers/builtin/venvStepBasedFlow.ts

@@ -615,7 +615,7 @@ export async function quickCreateVenv(
         allPackages.push(...additionalPackages);
     }
 
-    const validationError = result.validationError;
+    const validationError = result.validationErrors[0];
     if (operation && validationError) {
         throw new PythonToolError(
             'INVALID_PROJECT',
@@ -626,7 +626,11 @@ export async function quickCreateVenv(
             ),
         );
     }
-    const shouldProceed = operation || (await shouldProceedAfterPyprojectValidation(validationError, allPackages));
+    const shouldProceed =
+        operation ||
+        (await shouldProceedAfterPyprojectValidation(result.validationErrors, {
+            allPyprojectTomlsSelected: true,
+        }));
     if (!shouldProceed) {
         return undefined;
     }

src/managers/builtin/venvUtils.ts

@@ -108,6 +108,7 @@ function groupByInstalled(items: PackageQuickPickItem[], installed?: string[]):
 interface PackagesPickerResult {
     install: string[];
     uninstall: string[];
+    selectedUris?: Uri[];
 }
 
 function selectionsToResult(selections: string[], installed: string[]): PackagesPickerResult {
@@ -280,11 +281,12 @@ export async function selectFromInstallableToInstall(
     );
 
     if (selected) {
-        if (Array.isArray(selected)) {
-            return { install: selected.flatMap((s) => s.args ?? []), uninstall: [] };
-        } else {
-            return { install: selected.args ?? [], uninstall: [] };
-        }
+        const selectedItems = Array.isArray(selected) ? selected : [selected];
+        return {
+            install: selectedItems.flatMap((item) => item.args ?? []),
+            uninstall: [],
+            selectedUris: selectedItems.flatMap((item) => (item.uri ? [item.uri] : [])),
+        };
     }
     return undefined;
 }

src/managers/common/pickers.ts

@@ -1,5 +1,8 @@
 import assert from 'assert';
+import * as path from 'path';
+import * as sinon from 'sinon';
 import { Uri } from 'vscode';
+import * as windowApis from '../../../common/window.apis';
 import {
     PyprojectToml,
     shouldProceedAfterPyprojectValidation,
@@ -9,66 +12,103 @@ import {
 
 suite('pipUtils - validatePyproject', () => {
     suite('shouldProceedAfterPyprojectValidation', () => {
+        const invalidRoot = path.join(process.cwd(), 'test-data', 'invalid-project');
+        const otherRoot = path.join(process.cwd(), 'test-data', 'other-project');
         const mockValidationError: ValidationError = {
             message: 'Invalid package name "my package" in pyproject.toml.',
-            fileUri: Uri.file('/test/path/pyproject.toml'),
+            fileUri: Uri.file(path.join(invalidRoot, 'pyproject.toml')),
         };
+        let showErrorMessage: sinon.SinonStub;
+        let showTextDocument: sinon.SinonStub;
 
-        test('should return true when no validation error exists', async () => {
-            // Arrange: no validation error
-            const validationError = undefined;
-            const install = ['-e', '/test/path'];
+        setup(() => {
+            showErrorMessage = sinon.stub(windowApis, 'showErrorMessage');
+            showTextDocument = sinon.stub(windowApis, 'showTextDocument').resolves({} as never);
+        });
 
-            // Act
-            const result = await shouldProceedAfterPyprojectValidation(validationError, install);
+        teardown(() => sinon.restore());
 
-            // Assert
-            assert.strictEqual(result, true, 'Should proceed when no validation error');
+        test('returns true when no validation error exists', async () => {
+            assert.strictEqual(await shouldProceedAfterPyprojectValidation([]), true);
+            assert.ok(showErrorMessage.notCalled);
         });
 
-        test('should return true when install array is empty', async () => {
-            // Arrange: validation error exists but no packages selected
-            const install: string[] = [];
+        test('does not block when no pyproject.toml or a different file was selected', async () => {
+            assert.strictEqual(await shouldProceedAfterPyprojectValidation([mockValidationError]), true);
+            assert.strictEqual(
+                await shouldProceedAfterPyprojectValidation([mockValidationError], {
+                    selectedPyprojectTomls: [Uri.file(path.join(otherRoot, 'pyproject.toml'))],
+                }),
+                true,
+            );
+            assert.ok(showErrorMessage.notCalled);
+        });
 
-            // Act
-            const result = await shouldProceedAfterPyprojectValidation(mockValidationError, install);
+        test('does not confuse a bracketed sibling directory with extras from the invalid project', async () => {
+            const bracketedSibling = Uri.file(`${invalidRoot}[docs]` + path.sep + 'pyproject.toml');
+
+            const result = await shouldProceedAfterPyprojectValidation([mockValidationError], {
+                selectedPyprojectTomls: [bracketedSibling],
+            });
 
-            // Assert
-            assert.strictEqual(result, true, 'Should proceed when no packages selected');
+            assert.strictEqual(result, true);
+            assert.ok(showErrorMessage.notCalled);
         });
 
-        test('should return true when only requirements.txt packages selected (no -e flag)', async () => {
-            // Arrange: validation error exists but only requirements.txt packages selected
-            const install = ['-r', '/test/requirements.txt'];
+        test('continues when Continue Anyway is selected for the matching pyproject', async () => {
+            showErrorMessage.callsFake(async (...args: unknown[]) => args[2] as never);
 
-            // Act
-            const result = await shouldProceedAfterPyprojectValidation(mockValidationError, install);
+            const result = await shouldProceedAfterPyprojectValidation([mockValidationError], {
+                selectedPyprojectTomls: [mockValidationError.fileUri],
+            });
 
-            // Assert
-            assert.strictEqual(result, true, 'Should proceed when no TOML packages selected');
+            assert.strictEqual(result, true);
+            assert.ok(showErrorMessage.calledOnce);
+            assert.ok(showTextDocument.notCalled);
         });
 
-        test('should return true when only PyPI packages selected (no flags at all)', async () => {
-            // Arrange: only PyPI package names, no flags
-            const install = ['numpy', 'pandas', 'requests'];
+        test('opens the matching pyproject and stops creation when Open is selected', async () => {
+            showErrorMessage.callsFake(async (...args: unknown[]) => args[1] as never);
 
-            // Act
-            const result = await shouldProceedAfterPyprojectValidation(mockValidationError, install);
+            const result = await shouldProceedAfterPyprojectValidation([mockValidationError], {
+                selectedPyprojectTomls: [mockValidationError.fileUri],
+            });
 
-            // Assert
-            assert.strictEqual(result, true, 'Should proceed when only PyPI packages selected');
+            assert.strictEqual(result, false);
+            assert.ok(showTextDocument.calledOnceWithExactly(mockValidationError.fileUri));
         });
 
-        test('should not trigger on -e flag at end of array without following argument', async () => {
-            // Arrange: -e flag is last item (malformed, but should not crash)
-            const install = ['numpy', '-e'];
-            // This is edge case - -e at end means no path follows, so index + 1 < arr.length is false
+        test('stops creation without opening the file when Cancel is selected', async () => {
+            showErrorMessage.callsFake(async (...args: unknown[]) => args[3] as never);
 
-            // Act
-            const result = await shouldProceedAfterPyprojectValidation(mockValidationError, install);
+            const result = await shouldProceedAfterPyprojectValidation([mockValidationError], {
+                selectedPyprojectTomls: [mockValidationError.fileUri],
+            });
 
-            // Assert
-            assert.strictEqual(result, true, 'Should not crash on malformed -e flag at end');
+            assert.strictEqual(result, false);
+            assert.ok(showTextDocument.notCalled);
+        });
+
+        test('stops creation when the validation dialog is dismissed', async () => {
+            showErrorMessage.resolves(undefined);
+
+            const result = await shouldProceedAfterPyprojectValidation([mockValidationError], {
+                selectedPyprojectTomls: [mockValidationError.fileUri],
+            });
+
+            assert.strictEqual(result, false);
+            assert.ok(showTextDocument.notCalled);
+        });
+
+        test('prompts for an invalid-file-only Quick Create selection', async () => {
+            showErrorMessage.callsFake(async (...args: unknown[]) => args[3] as never);
+
+            const result = await shouldProceedAfterPyprojectValidation([mockValidationError], {
+                allPyprojectTomlsSelected: true,
+            });
+
+            assert.strictEqual(result, false);
+            assert.ok(showErrorMessage.calledOnce);
         });
     });
 
@@ -196,6 +236,65 @@ suite('pipUtils - validatePyproject', () => {
         });
     });
 
+    suite('validatePyprojectToml - Dependency Values', () => {
+        test('accepts dependency arrays containing strings', () => {
+            verifyValidationError(
+                {
+                    project: {
+                        name: 'test',
+                        dependencies: ['requests>=2', 'httpx'],
+                        'optional-dependencies': { test: ['pytest'] },
+                    },
+                    'build-system': { requires: ['setuptools'] },
+                },
+                undefined,
+            );
+        });
+
+        test('rejects project dependencies that are not an array of strings', () => {
+            const toml = {
+                project: { name: 'test', dependencies: 'requests' },
+            } as PyprojectToml;
+            assert.match(validatePyprojectToml(toml) ?? '', /dependencies.*array of strings/i);
+        });
+
+        test('rejects non-string entries in project dependencies', () => {
+            const toml = {
+                project: { name: 'test', dependencies: ['requests', 42] },
+            } as PyprojectToml;
+            assert.match(validatePyprojectToml(toml) ?? '', /dependencies.*array of strings/i);
+        });
+
+        test('rejects optional dependencies that are not a table', () => {
+            const toml = {
+                project: { name: 'test', 'optional-dependencies': ['pytest'] },
+            } as PyprojectToml;
+            assert.match(validatePyprojectToml(toml) ?? '', /optional-dependencies.*table/i);
+        });
+
+        test('rejects invalid optional dependency group names', () => {
+            const toml = {
+                project: { name: 'test', 'optional-dependencies': { 'bad extra': ['pytest'] } },
+            } as PyprojectToml;
+            assert.match(validatePyprojectToml(toml) ?? '', /invalid optional dependency group name/i);
+        });
+
+        test('rejects optional dependency groups that are not arrays of strings', () => {
+            const toml = {
+                project: { name: 'test', 'optional-dependencies': { test: 'pytest' } },
+            } as PyprojectToml;
+            assert.match(validatePyprojectToml(toml) ?? '', /group.*array of strings/i);
+        });
+
+        test('rejects build-system requirements that are not arrays of strings', () => {
+            const toml = {
+                project: { name: 'test' },
+                'build-system': { requires: 'setuptools' },
+            } as PyprojectToml;
+            assert.match(validatePyprojectToml(toml) ?? '', /requires.*array of strings/i);
+        });
+    });
+
     suite('validatePyprojectToml - Required Fields (PEP 621)', () => {
         test('should accept valid project with name', () => {
             const toml: PyprojectToml = {