Preserve legacy package version lookup behavior

Add an opt-in throw mode for callers that need to distinguish unsupported lookups from operational failures.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 4c801599-6aaa-4eb5-b4ed-23362ed54dbd

Author: edvilme

api/CHANGELOG.md

@@ -11,10 +11,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Added `PackageVersionLookupNotSupportedError`, thrown when a package manager cannot list a package's available versions (an unsupported capability, as distinct from an operational failure). The error exposes a stable `code` (`'PackageVersionLookupNotSupported'`) discriminator.
 - Added the `isPackageVersionLookupNotSupportedError(error): error is PackageVersionLookupNotSupportedError` type guard. It recognizes the error via its stable `code`, so it works even when the error crosses an extension bundle boundary and `instanceof` would fail.
+- Added an optional `errorMode` to `PythonPackageGetterApi.getPackageAvailableVersions`. The default `legacy` mode preserves the existing `undefined` result for unsupported lookups and operational failures. The opt-in `throw` mode rejects with `PackageVersionLookupNotSupportedError` for unsupported capabilities and propagates operational failures unchanged.
 
 ### Changed
 
-- `PythonPackageGetterApi.getPackageAvailableVersions` now distinguishes an unsupported capability from an operational failure. It rejects with `PackageVersionLookupNotSupportedError` when the environment's package manager does not support version lookup (the default/missing manager, Poetry, or a Pip older than 21.2), and it propagates the original error for operational failures (command, network, or malformed/unparseable output) instead of resolving to `undefined`. On success it resolves to a non-empty array of versions, and its return type is now `Promise<Pep440Version[]>`.
 - Documented that `PackageManager.getPackageAvailableVersions` implementations should throw `PackageVersionLookupNotSupportedError` when version lookup is unsupported and let operational failures propagate. Resolving to `undefined` continues to be treated by callers as an unsupported capability.
 
 ## [1.2.0]

api/test/consumer.ts

@@ -15,12 +15,23 @@ type Equal<Left, Right> =
 type AvailableVersionsReturn = ReturnType<PythonPackageGetterApi['getPackageAvailableVersions']>;
 type RefreshReturn = ReturnType<PackageManager['refresh']>;
 
-const availableVersionsReturnIsExact: Equal<AvailableVersionsReturn, Promise<Pep440Version[]>> = true;
+const availableVersionsReturnIsExact: Equal<AvailableVersionsReturn, Promise<Pep440Version[] | undefined>> = true;
 const refreshReturnIsExact: Equal<RefreshReturn, Promise<void>> = true;
 
 declare const api: PythonPackageGetterApi;
 declare const environment: PythonEnvironment;
-const availableVersions: Promise<Pep440Version[]> = api.getPackageAvailableVersions(environment, 'example');
+const legacyAvailableVersions: Promise<Pep440Version[] | undefined> = api.getPackageAvailableVersions(
+    environment,
+    'example',
+);
+const explicitLegacyAvailableVersions: Promise<Pep440Version[] | undefined> = api.getPackageAvailableVersions(
+    environment,
+    'example',
+    { errorMode: 'legacy' },
+);
+const throwingAvailableVersions: Promise<Pep440Version[]> = api.getPackageAvailableVersions(environment, 'example', {
+    errorMode: 'throw',
+});
 
 // The unsupported-capability error is part of the public contract: it is constructible, extends
 // Error, and exposes a stable string-literal `code` discriminator.
@@ -36,7 +47,9 @@ const guardNarrows: boolean = isPackageVersionLookupNotSupportedError(maybeError
 
 void availableVersionsReturnIsExact;
 void refreshReturnIsExact;
-void availableVersions;
+void legacyAvailableVersions;
+void explicitLegacyAvailableVersions;
+void throwingAvailableVersions;
 void lookupErrorIsError;
 void lookupErrorCodeIsExact;
 void guardNarrows;

src/api.ts

@@ -1179,6 +1179,22 @@ export function isPackageVersionLookupNotSupportedError(
     );
 }
 
+/**
+ * Controls how package version lookup failures are reported.
+ */
+export interface GetPackageAvailableVersionsOptions {
+    /**
+     * Determines whether lookup failures preserve the legacy `undefined` result or reject.
+     *
+     * - `legacy` resolves to `undefined` for unsupported lookups and operational failures.
+     *   This remains the default for backward compatibility, but may be removed in a future
+     *   major API version.
+     * - `throw` rejects with {@link PackageVersionLookupNotSupportedError} for unsupported
+     *   lookups and propagates operational failures unchanged.
+     */
+    errorMode?: 'legacy' | 'throw';
+}
+
 export interface PythonPackageGetterApi {
     /**
      * Refresh the list of packages in a Python Environment.
@@ -1200,24 +1216,27 @@ export interface PythonPackageGetterApi {
     /**
      * Get the list of available versions for a package, newest first.
      *
-     * The returned promise distinguishes an unsupported capability from an operational failure:
-     * - It resolves to a non-empty array of {@link Pep440Version} objects when versions are found.
-     * - It rejects with a {@link PackageVersionLookupNotSupportedError} when the environment's
-     *   package manager does not support version lookup (for example, the default/missing manager,
-     *   Poetry, or a Pip older than 21.2). Use {@link isPackageVersionLookupNotSupportedError} to
-     *   detect this reliably across extension bundle boundaries and fall back to manual entry.
-     * - It rejects with the original error for any other failure (command, network, or
-     *   malformed/unparseable output), which callers should handle or surface normally.
+     * By default, this preserves the legacy behavior of resolving to `undefined` for unsupported
+     * lookups and operational failures. Pass `{ errorMode: 'throw' }` to distinguish unsupported
+     * capabilities from operational failures: unsupported lookups reject with
+     * {@link PackageVersionLookupNotSupportedError}, while other failures propagate unchanged.
      *
      * @param environment The Python Environment context for the lookup.
      * @param packageName The name of the package to look up.
-     * @returns A promise that resolves to an array of {@link Pep440Version} objects (newest first).
-     * @throws {@link PackageVersionLookupNotSupportedError} when version lookup is unsupported.
+     * @param options Controls how lookup failures are reported.
+     * @returns A promise that resolves to an array of {@link Pep440Version} objects (newest first),
+     *          or `undefined` in legacy mode when lookup is unsupported or fails.
      */
     getPackageAvailableVersions(
         environment: PythonEnvironment,
         packageName: string,
+        options: GetPackageAvailableVersionsOptions & { errorMode: 'throw' },
     ): Promise<Pep440Version[]>;
+    getPackageAvailableVersions(
+        environment: PythonEnvironment,
+        packageName: string,
+        options?: GetPackageAvailableVersionsOptions,
+    ): Promise<Pep440Version[] | undefined>;
 
     /**
      * Event raised when the list of packages in a Python Environment changes.

src/features/envCommands.ts

@@ -378,7 +378,7 @@ export async function managePackageVersion(context: unknown, em: EnvironmentMana
         try {
             availableVersions = await withProgress(
                 { location: ProgressLocation.Window, title: l10n.t('Fetching available versions for {0}...', pkg.name) },
-                () => packageManager.getPackageAvailableVersions(environment, pkg.name),
+                () => packageManager.getPackageAvailableVersions(environment, pkg.name, { errorMode: 'throw' }),
             );
         } catch (error) {
             if (!isPackageVersionLookupNotSupportedError(error)) {

src/features/pythonApi.ts

@@ -10,6 +10,7 @@ import {
     EnvironmentManager,
     GetEnvironmentScope,
     GetEnvironmentsScope,
+    GetPackageAvailableVersionsOptions,
     GetPackagesOptions,
     Package,
     PackageId,
@@ -320,18 +321,32 @@ export class PythonEnvironmentApiImpl implements PythonEnvironmentApi {
         }
         return manager.getPackages(context, options);
     }
+    getPackageAvailableVersions(
+        context: PythonEnvironment,
+        packageName: string,
+        options: GetPackageAvailableVersionsOptions & { errorMode: 'throw' },
+    ): Promise<Pep440Version[]>;
+    getPackageAvailableVersions(
+        context: PythonEnvironment,
+        packageName: string,
+        options?: GetPackageAvailableVersionsOptions,
+    ): Promise<Pep440Version[] | undefined>;
     async getPackageAvailableVersions(
         context: PythonEnvironment,
         packageName: string,
-    ): Promise<Pep440Version[]> {
+        options?: GetPackageAvailableVersionsOptions,
+    ): Promise<Pep440Version[] | undefined> {
         await waitForEnvManagerId([context.envId.managerId]);
         const manager = this.envManagers.getPackageManager(context);
         if (!manager) {
-            throw new PackageVersionLookupNotSupportedError(
-                `No package manager is available to look up versions for: ${context.envId.id}`,
-            );
+            if (options?.errorMode === 'throw') {
+                throw new PackageVersionLookupNotSupportedError(
+                    `No package manager is available to look up versions for: ${context.envId.id}`,
+                );
+            }
+            return undefined;
         }
-        return manager.getPackageAvailableVersions(context, packageName);
+        return manager.getPackageAvailableVersions(context, packageName, options);
     }
     onDidChangePackages: Event<DidChangePackagesEventArgs> = this._onDidChangePackages.event;
 

src/internal.api.ts

@@ -10,6 +10,7 @@ import {
     EnvironmentManager,
     GetEnvironmentScope,
     GetEnvironmentsScope,
+    GetPackageAvailableVersionsOptions,
     GetPackagesOptions,
     IconPath,
     Package,
@@ -398,30 +399,45 @@ export class InternalPackageManager implements PackageManager {
         return this.manager.getVersion ? this.manager.getVersion(environment) : Promise.resolve(undefined);
     }
 
+    getPackageAvailableVersions(
+        environment: PythonEnvironment,
+        packageName: string,
+        options: GetPackageAvailableVersionsOptions & { errorMode: 'throw' },
+    ): Promise<Pep440Version[]>;
+    getPackageAvailableVersions(
+        environment: PythonEnvironment,
+        packageName: string,
+        options?: GetPackageAvailableVersionsOptions,
+    ): Promise<Pep440Version[] | undefined>;
+
     /**
-     * Delegates version lookup to the underlying package manager.
-     *
-     * Managers that do not implement version lookup - or that resolve `undefined` - are treated
-     * as lacking the capability, so this rejects with {@link PackageVersionLookupNotSupportedError}.
-     * All other errors from the manager propagate unchanged.
+     * Delegates version lookup to the underlying package manager using the requested error mode.
      */
     async getPackageAvailableVersions(
         environment: PythonEnvironment,
         packageName: string,
-    ): Promise<Pep440Version[]> {
-        if (!this.manager.getPackageAvailableVersions) {
-            throw new PackageVersionLookupNotSupportedError(
-                `Package version lookup is not supported by package manager: ${this.id}`,
-            );
-        }
-        const versions = await this.manager.getPackageAvailableVersions(environment, packageName);
-        if (versions === undefined) {
-            // A manager that resolves `undefined` is signalling the capability is unavailable.
-            throw new PackageVersionLookupNotSupportedError(
-                `Package version lookup is not supported by package manager: ${this.id}`,
-            );
+        options?: GetPackageAvailableVersionsOptions,
+    ): Promise<Pep440Version[] | undefined> {
+        const shouldThrow = options?.errorMode === 'throw';
+        try {
+            if (!this.manager.getPackageAvailableVersions) {
+                throw new PackageVersionLookupNotSupportedError(
+                    `Package version lookup is not supported by package manager: ${this.id}`,
+                );
+            }
+            const versions = await this.manager.getPackageAvailableVersions(environment, packageName);
+            if (versions === undefined && shouldThrow) {
+                throw new PackageVersionLookupNotSupportedError(
+                    `Package version lookup is not supported by package manager: ${this.id}`,
+                );
+            }
+            return versions;
+        } catch (error) {
+            if (shouldThrow) {
+                throw error;
+            }
+            return undefined;
         }
-        return versions;
     }
 
     getDirectPackageNames(environment: PythonEnvironment): Promise<Set<string> | undefined> {

src/test/api.packageVersionLookupError.unit.test.ts

@@ -0,0 +1,31 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import * as assert from 'assert';
+import { isPackageVersionLookupNotSupportedError, PackageVersionLookupNotSupportedError } from '../api';
+
+suite('PackageVersionLookupNotSupportedError', () => {
+    test('is an Error subclass with a stable code and name', () => {
+        const error = new PackageVersionLookupNotSupportedError('nope');
+        assert.ok(error instanceof Error);
+        assert.strictEqual(error.code, 'PackageVersionLookupNotSupported');
+        assert.strictEqual(error.name, 'PackageVersionLookupNotSupportedError');
+        assert.strictEqual(error.message, 'nope');
+    });
+
+    test('type guard recognizes a cross-bundle error via its stable code (without instanceof)', () => {
+        const crossBundle = {
+            name: 'PackageVersionLookupNotSupportedError',
+            code: 'PackageVersionLookupNotSupported',
+            message: 'from another bundle',
+        };
+        assert.strictEqual(crossBundle instanceof PackageVersionLookupNotSupportedError, false);
+        assert.ok(isPackageVersionLookupNotSupportedError(crossBundle));
+    });
+
+    test('type guard rejects unrelated errors and values', () => {
+        assert.strictEqual(isPackageVersionLookupNotSupportedError(new Error('other')), false);
+        assert.strictEqual(isPackageVersionLookupNotSupportedError({ code: 'ENOENT' }), false);
+        assert.strictEqual(isPackageVersionLookupNotSupportedError(null), false);
+    });
+});

src/test/integration/packageManager.integration.test.ts

@@ -3,7 +3,13 @@ import * as vscode from 'vscode';
 import { compare } from '@renovatebot/pep440';
 import assert from 'assert';
 import * as path from 'path';
-import { Package, PythonEnvironment, PythonEnvironmentApi, PythonProject } from '../../api';
+import {
+    Package,
+    PythonEnvironment,
+    PythonEnvironmentApi,
+    PythonProject,
+    isPackageVersionLookupNotSupportedError,
+} from '../../api';
 import { CONDA_MANAGER_ID, DEFAULT_PACKAGE_MANAGER_ID, VENV_MANAGER_ID } from '../../common/constants';
 import { PythonProjectSettings } from '../../internal.api';
 import { getConda } from '../../managers/conda/condaUtils';
@@ -210,12 +216,23 @@ for (const profile of profiles) {
         test(`${profile.name} Package Manager should list available package versions`, async function () {
             const packages = await api.getPackages(environment!, { skipCache: true });
             assert.ok(packages, 'Unable to list packages before version lookup');
+
             if (!profile.supportsVersionLookup(packages)) {
+                // The profile declares that the active manager/tool version does not support
+                // version lookup, so the API must surface the typed unsupported-capability error
+                // rather than an operational failure. Assert that contract, then skip.
+                await assert.rejects(
+                    () => api.getPackageAvailableVersions(environment!, 'requests', { errorMode: 'throw' }),
+                    (error: unknown) => isPackageVersionLookupNotSupportedError(error),
+                    `${profile.name} did not report unsupported version lookup with the typed error`,
+                );
                 this.skip();
                 return;
             }
 
-            const versions = await api.getPackageAvailableVersions(environment!, 'requests');
+            // Supported profiles must resolve to a defined, non-empty result; operational failures
+            // propagate and fail the test instead of silently resolving to undefined.
+            const versions = await api.getPackageAvailableVersions(environment!, 'requests', { errorMode: 'throw' });
             assert.ok(versions, `${profile.name} unexpectedly failed to retrieve package versions`);
             assert.ok(versions.length > 0, 'No package versions available');
         });

src/test/internalPackageManager.versionLookup.unit.test.ts

@@ -0,0 +1,45 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import * as assert from 'assert';
+import { isPackageVersionLookupNotSupportedError, PackageManager, PythonEnvironment } from '../api';
+import { InternalPackageManager } from '../internal.api';
+
+suite('InternalPackageManager.getPackageAvailableVersions', () => {
+    const environment = { envId: { id: 'env', managerId: 'mgr' } } as PythonEnvironment;
+
+    test('legacy mode resolves undefined when the manager does not implement lookup', async () => {
+        const manager = new InternalPackageManager('test:manager', {} as unknown as PackageManager);
+        assert.strictEqual(await manager.getPackageAvailableVersions(environment, 'requests'), undefined);
+    });
+
+    test('throw mode rejects with the typed unsupported error when the manager does not implement lookup', async () => {
+        const manager = new InternalPackageManager('test:manager', {} as unknown as PackageManager);
+        await assert.rejects(
+            () => manager.getPackageAvailableVersions(environment, 'requests', { errorMode: 'throw' }),
+            (error: unknown) => isPackageVersionLookupNotSupportedError(error),
+        );
+    });
+
+    test('legacy mode resolves undefined for operational errors', async () => {
+        const manager = new InternalPackageManager('test:manager', {
+            getPackageAvailableVersions: async () => {
+                throw new Error('network down');
+            },
+        } as unknown as PackageManager);
+        assert.strictEqual(await manager.getPackageAvailableVersions(environment, 'requests'), undefined);
+    });
+
+    test('throw mode propagates operational errors from the underlying manager', async () => {
+        const operational = new Error('network down');
+        const manager = new InternalPackageManager('test:manager', {
+            getPackageAvailableVersions: async () => {
+                throw operational;
+            },
+        } as unknown as PackageManager);
+        await assert.rejects(
+            () => manager.getPackageAvailableVersions(environment, 'requests', { errorMode: 'throw' }),
+            (error: unknown) => error === operational && !isPackageVersionLookupNotSupportedError(error),
+        );
+    });
+});