fix: address remaining API PR comments

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

Copilot-Session: de4cb63f-4a85-432d-a722-697b33e9d49a

Author: edvilme

CONTRIBUTING.md

@@ -96,7 +96,7 @@ The npm package under [`api/`](./api) is the public API facade other extensions
 - Edit the public API only in `src/api.ts` (the runtime facade: `PythonEnvironments.api()` helper and `EXTENSION_ID`), `src/types.ts` (public contracts: interfaces, types, enums), and `src/publicErrors.ts` (concrete public error classes and type guards). `api/src/*.ts` files are build artifacts — never edit or commit them.
 - `api/src/main.ts`, `api/src/types.ts`, and `api/src/publicErrors.ts` are produced by the publish pipeline ([`build/azure-pipeline.npm.yml`](./build/azure-pipeline.npm.yml)), which copies `src/api.ts` to `api/src/main.ts`, `src/types.ts` to `api/src/types.ts`, and `src/publicErrors.ts` to `api/src/publicErrors.ts` before compiling. The api package is therefore built in CI only; to build it locally, copy the files first (e.g. `cp src/api.ts api/src/main.ts && cp src/types.ts api/src/types.ts && cp src/publicErrors.ts api/src/publicErrors.ts`).
 - `src/api.ts`, `src/types.ts`, and `src/publicErrors.ts` are validated on every PR by the extension's own lint and TypeScript compile.
-- **Versioning:** the published package version in [`api/package.json`](./api/package.json) is maintained independently of the extension version in [`package.json`](./package.json) — the two do not need to match. Any PR that edits `src/api.ts`, `src/types.ts`, or `src/publicErrors.ts` must bump `api/package.json` (use the `skip api version` label to bypass) and add an entry to [`api/CHANGELOG.md`](./api/CHANGELOG.md) (use the `skip api changelog` label to bypass).
+- **Versioning and compatibility:** the published package version in [`api/package.json`](./api/package.json) is maintained independently of the extension version in [`package.json`](./package.json) — the two do not need to match. Compatibility is based on the API shape exported by the installed Python Environments extension at runtime. Package updates must preserve backwards-compatible contracts unless the API package version intentionally communicates a breaking change; consumers should treat newly added members as optional when they may run against older installed extension versions. Any PR that edits `src/api.ts`, `src/types.ts`, or `src/publicErrors.ts` must bump `api/package.json` (use the `skip api version` label to bypass) and add an entry to [`api/CHANGELOG.md`](./api/CHANGELOG.md) (use the `skip api changelog` label to bypass).
 
 ## Questions or Issues?
 

api/scripts/test-package.cjs

@@ -83,7 +83,17 @@ try {
     fs.writeFileSync(path.join(vscodeStubRoot, 'package.json'), JSON.stringify({ main: 'index.js' }));
     fs.writeFileSync(
         path.join(vscodeStubRoot, 'index.js'),
-        "exports.extensions = { getExtension: () => undefined };",
+        [
+            "const runtimeApi = { getEnvironments: async () => [] };",
+            "const extension = {",
+            "  isActive: false,",
+            "  exports: undefined,",
+            "  packageJSON: { version: '1.37.0' },",
+            "  activate: async () => { extension.isActive = true; extension.exports = runtimeApi; return runtimeApi; },",
+            "};",
+            'exports.__runtimeApi = runtimeApi;',
+            'exports.extensions = { getExtension: () => extension };',
+        ].join('\n'),
     );
     const installedPackageJson = JSON.parse(fs.readFileSync(path.join(installedPackageRoot, 'package.json'), 'utf8'));
     assert.strictEqual(installedPackageJson.main, './out/cjs/main.cjs');
@@ -117,6 +127,24 @@ try {
         'function',
         'CommonJS consumers should load the package runtime facade',
     );
+    execFileSync(
+        process.execPath,
+        [
+            '--eval',
+            [
+                "const packageModule = require('@vscode/python-environments');",
+                "const vscode = require('vscode');",
+                "(async () => {",
+                '  const api = await packageModule.PythonEnvironments.api();',
+                '  if (api !== vscode.__runtimeApi) process.exit(1);',
+                '})().catch(() => process.exit(1));',
+            ].join('\n'),
+        ],
+        {
+            cwd: path.join(testRoot, 'legacy'),
+            encoding: 'utf8',
+        },
+    );
     assert.strictEqual(
         canonicalPath(requireFromConsumer.resolve('@vscode/python-environments')),
         canonicalPath(path.join(installedPackageRoot, installedPackageJson.exports.require.default)),
@@ -128,7 +156,7 @@ try {
         [
             '--input-type=module',
             '--eval',
-            "const packageModule = await import('@vscode/python-environments'); if (typeof packageModule.PythonEnvironments.api !== 'function') process.exit(1); console.log(import.meta.resolve('@vscode/python-environments'));",
+            "const packageModule = await import('@vscode/python-environments'); const vscode = await import('vscode'); if (typeof packageModule.PythonEnvironments.api !== 'function') process.exit(1); const api = await packageModule.PythonEnvironments.api(); if (api !== vscode.default.__runtimeApi) process.exit(1); console.log(import.meta.resolve('@vscode/python-environments'));",
         ],
         {
             cwd: path.join(testRoot, 'modern'),

api/test/consumer.ts

@@ -2,11 +2,13 @@ import type {
     PackageManager,
     Pep440Version,
     PythonEnvironment,
+    PythonEnvironmentApi,
     PythonPackageGetterApi,
 } from '@vscode/python-environments';
 import {
     isPackageVersionLookupNotSupportedError,
     PackageVersionLookupNotSupportedError,
+    PythonEnvironments,
 } from '@vscode/python-environments';
 
 type Equal<Left, Right> =
@@ -32,6 +34,7 @@ const explicitLegacyAvailableVersions: Promise<Pep440Version[] | undefined> = ap
 const throwingAvailableVersions: Promise<Pep440Version[]> = api.getPackageAvailableVersions(environment, 'example', {
     errorMode: 'throw',
 });
+const runtimeApi: Promise<PythonEnvironmentApi> = PythonEnvironments.api();
 
 // The unsupported-capability error is part of the public contract: it is constructible, extends
 // Error, and exposes a stable string-literal `code` discriminator.
@@ -50,6 +53,7 @@ void refreshReturnIsExact;
 void legacyAvailableVersions;
 void explicitLegacyAvailableVersions;
 void throwingAvailableVersions;
+void runtimeApi;
 void lookupErrorIsError;
 void lookupErrorCodeIsExact;
 void guardNarrows;

src/features/projectManager.ts

@@ -1,5 +1,5 @@
 import * as path from 'path';
-import { Disposable, Event, EventEmitter, MarkdownString, Uri, workspace } from 'vscode';
+import { Disposable, Event, EventEmitter, MarkdownString, Uri } from 'vscode';
 import type { IconPath, PythonProject } from '../api';
 import { DEFAULT_ENV_MANAGER_ID, DEFAULT_PACKAGE_MANAGER_ID } from '../common/constants';
 import { createSimpleDebounce } from '../common/utils/debounce';
@@ -50,11 +50,11 @@ export interface InlineScriptProjectRegistrationMarker {
 }
 
 export class PythonProjectsImpl implements PythonProject {
-    name: string;
-    uri: Uri;
-    description?: string;
-    tooltip?: string | MarkdownString;
-    iconPath?: IconPath;
+    readonly name: string;
+    readonly uri: Uri;
+    readonly description?: string;
+    readonly tooltip?: string | MarkdownString;
+    readonly iconPath?: IconPath;
 
     constructor(
         name: string,
@@ -257,7 +257,7 @@ export class PythonProjectManagerImpl implements PythonProjectManager {
         const envManagerId = getDefaultEnvManagerSetting(this);
         const pkgManagerId = getDefaultPkgManagerSetting(this);
 
-        const globalConfig = workspace.getConfiguration('python-envs', undefined);
+        const globalConfig = getConfiguration('python-envs', undefined);
         const defaultEnvManager = globalConfig.get<string>('defaultEnvManager', DEFAULT_ENV_MANAGER_ID);
         const defaultPkgManager = globalConfig.get<string>('defaultPackageManager', DEFAULT_PACKAGE_MANAGER_ID);
 

src/test/features/envCommands.unit.test.ts

@@ -45,7 +45,7 @@ suite('Environment removal command ownership', () => {
                 envPath: path.join(process.cwd(), 'removal-env'),
             });
             const remove = sinon.stub().resolves();
-            const owner =             new InternalEnvironmentManager(managerId, {
+            const owner = new InternalEnvironmentManager(managerId, {
                 name: 'test',
                 preferredPackageManagerId: 'ms-python.python:pip',
                 get: async () => environment,

src/types.ts

@@ -503,24 +503,21 @@ export interface EnvironmentManager {
     onDidChangeEnvironment?: Event<DidChangeEnvironmentEventArgs>;
 
     /**
-     * Resolves the specified Python environment. The environment can be either a {@link PythonEnvironment} or a {@link Uri} context.
+     * Resolves the Python environment associated with the specified URI context.
      *
-     * This method is used to obtain a fully detailed {@link PythonEnvironment} object. The input can be:
-     * - A {@link PythonEnvironment} object, which might be missing key details such as {@link PythonEnvironment.execInfo}.
-     * - A {@link Uri} object, which typically represents either:
-     *   - A folder that contains the Python environment.
-     *   - The path to a Python executable.
+     * This method is used to obtain a fully detailed {@link PythonEnvironment} object. The input
+     * URI typically represents either a folder that contains the Python environment or the path to
+     * a Python executable.
      *
-     * @param context - The context for resolving the environment, which can be a {@link PythonEnvironment} or a {@link Uri}.
+     * @param context - The URI context for resolving the environment.
      * @returns A promise that resolves to the fully detailed {@link PythonEnvironment}, or `undefined` if the environment cannot be resolved.
      *
      * @remarks
-     * Called to turn a lightly-populated {@link PythonEnvironment} or a {@link Uri}
-     * pointing at an interpreter or environment folder into a fully-populated
-     * {@link PythonEnvironment} with complete {@link PythonEnvironment.execInfo}. Typical
-     * triggers include the user manually selecting an interpreter path, resolving
-     * `python.defaultInterpreterPath` at startup, and populating execution details before
-     * launching Python.
+     * Called to turn a {@link Uri} pointing at an interpreter or environment folder into a
+     * fully-populated {@link PythonEnvironment} with complete {@link PythonEnvironment.execInfo}.
+     * Typical triggers include the user manually selecting an interpreter path, resolving
+     * `python.defaultInterpreterPath` at startup, and populating execution details before launching
+     * Python.
      */
     resolve(context: ResolveEnvironmentContext): Promise<PythonEnvironment | undefined>;
 
@@ -1080,10 +1077,10 @@ export interface PythonEnvironmentsApi {
     onDidChangeEnvironments: Event<DidChangeEnvironmentsEventArgs>;
 
     /**
-     * This method is used to get the details missing from a PythonEnvironment. Like
-     * {@link PythonEnvironment.execInfo} and other details.
+     * This method is used to get the details for the Python environment associated with a URI
+     * context, such as an interpreter path or environment folder.
      *
-     * @param context : The PythonEnvironment or Uri for which details are required.
+     * @param context - The URI context for which environment details are required.
      */
     resolveEnvironment(context: ResolveEnvironmentContext): Promise<PythonEnvironment | undefined>;
 }