Enforce matching extension and API package versions

Add scripts/compare_package_versions.py and a CI job to verify the
extension (package.json) and published API package (api/package.json)
share the same version. Bump api package to 1.37.0 to match. Add a
check-for-changed-files gate requiring an api/package.json version bump
when src/api.ts changes (bypass with the 'skip api version' label).

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

Author: edvilme

.github/workflows/pr-file-check.yml

@@ -41,3 +41,28 @@ jobs:
             src/**/*.unit.test.ts
           skip-label: 'skip tests'
           failure-message: 'TypeScript code was edited without also editing a test file (the ${skip-label} label can be used to pass this check)'
+
+      - name: 'Public API changes require a version bump'
+        uses: brettcannon/check-for-changed-files@871d7b8b5917a4f6f06662e2262e8ffc51dff6d1 # v1.2.1
+        with:
+          prereq-pattern: 'src/api.ts'
+          file-pattern: 'api/package.json'
+          skip-label: 'skip api version'
+          failure-message: 'The public API (${prereq-pattern}) was changed without bumping the package version in ${file-pattern} (the ${skip-label} label can be used to pass this check)'
+
+  version-match:
+    name: 'Extension and API package versions match'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+
+      - name: 'Compare package.json versions'
+        run: python scripts/compare_package_versions.py

CONTRIBUTING.md

@@ -96,6 +96,7 @@ The npm package under [`api/`](./api) is the public API facade other extensions
 - Edit the API only in `src/api.ts`. This file contains the full public surface, including the runtime `PythonEnvironments.api()` helper and `EXTENSION_ID`. `api/src/main.ts` is a build artifact — never edit or commit it.
 - `api/src/main.ts` is 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` before compiling. The api package is therefore built in CI only; to build it locally, copy the file first (e.g. `cp src/api.ts api/src/main.ts`).
 - `src/api.ts` itself is 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) must always match the extension version in [`package.json`](./package.json). CI enforces this via [`scripts/compare_package_versions.py`](./scripts/compare_package_versions.py). Additionally, any PR that edits `src/api.ts` must bump `api/package.json` (use the `skip api version` label to bypass). When bumping, update both files so they stay in sync.
 
 ## Questions or Issues?
 

api/package-lock.json

@@ -1,7 +1,7 @@
 {
     "name": "@vscode/python-environments",
     "description": "An API facade for the Python Environments extension in VS Code",
-    "version": "1.0.0",
+    "version": "1.37.0",
     "author": {
         "name": "Microsoft Corporation"
     },

api/package.json

@@ -0,0 +1,75 @@
+#!/usr/bin/env python3
+"""Verify that the extension and the public API npm package share the same version.
+
+The root ``package.json`` (the VS Code extension) and ``api/package.json`` (the
+published ``@vscode/python-environments`` npm package) must always declare the same
+``version``. This keeps the published API package in lock-step with the extension
+that implements it.
+
+Exits with status 0 when the versions match, and status 1 (printing an error) when
+they differ. Intended to be run from CI, but can also be run locally:
+
+    python scripts/compare_package_versions.py
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+EXTENSION_PACKAGE = REPO_ROOT / "package.json"
+API_PACKAGE = REPO_ROOT / "api" / "package.json"
+
+
+def read_version(package_json: Path) -> str:
+    """Return the ``version`` field from the given package.json file.
+
+    Args:
+        package_json: Path to a ``package.json`` file.
+
+    Returns:
+        The declared version string.
+
+    Raises:
+        SystemExit: If the file is missing, unparseable, or has no ``version``.
+    """
+    try:
+        data = json.loads(package_json.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        sys.exit(f"::error::{package_json} not found")
+    except json.JSONDecodeError as exc:
+        sys.exit(f"::error::Failed to parse {package_json}: {exc}")
+
+    version = data.get("version")
+    if not isinstance(version, str) or not version:
+        sys.exit(f"::error::{package_json} is missing a 'version' field")
+    return version
+
+
+def main() -> int:
+    """Compare the extension and API package versions.
+
+    Returns:
+        0 when the versions match, 1 when they differ.
+    """
+    extension_version = read_version(EXTENSION_PACKAGE)
+    api_version = read_version(API_PACKAGE)
+
+    print(f"Extension version (package.json):       {extension_version}")
+    print(f"API package version (api/package.json): {api_version}")
+
+    if extension_version != api_version:
+        print(
+            f"::error::Version mismatch: package.json is {extension_version} but "
+            f"api/package.json is {api_version}. Update api/package.json to match."
+        )
+        return 1
+
+    print("Versions match.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())