Generate published API entry point from src/api.ts (#1619)

## Summary

The npm package `@vscode/python-environments` previously duplicated the
**entire** API definition in `api/src/main.ts` — a near-copy of
`src/api.ts` that was hand-maintained and had already drifted (dozens of
differing lines).

This PR makes **`src/api.ts` the single source of truth**, stops
committing the duplicate, and adds CI guardrails so public API changes
are versioned and documented.

## What changed

- **`src/api.ts`** — folded in the publish-only runtime helper so it is
now the complete public surface: the `PythonEnvironments.api()` helper
and `EXTENSION_ID`. The extension itself never calls this helper (it
*implements* the API), so it is harmless dead code in the extension
bundle; a bonus is that consumers who copy `src/api.ts` (per
`examples/README.md`) now also get the helper.
- **`api/src/main.ts`** — removed. It is now generated at publish time
and ignored via **`api/.gitignore`**.
- **`build/azure-pipeline.npm.yml`** — added a step that copies
`src/api.ts` to `api/src/main.ts` before compiling the package.
- **`api/package.json`** / **`api/package-lock.json`** — bumped to
`1.37.0` to match the extension version.
- **`api/CHANGELOG.md`** — new changelog for the published package (Keep
a Changelog format).
- **`scripts/compare_package_versions.py`** — new script that verifies
the extension (`package.json`) and API package (`api/package.json`)
declare the same version.
- **`.github/workflows/pr-file-check.yml`** — added CI guardrails (see
below).
- **`CONTRIBUTING.md`** — documents the copy model and the
versioning/changelog rules.

## How it works now

The publish pipeline runs: `npm install` -> **`cp ../src/api.ts
src/main.ts`** -> `npm run compile` -> `npm pack --ignore-scripts`.
`src/api.ts` is validated on every PR by the extension's own lint +
`tsc`.

## CI guardrails

- **Version match** — a `version-match` job runs
`scripts/compare_package_versions.py` and fails if `package.json` and
`api/package.json` versions differ.
- **API change requires a version bump** — if a PR edits `src/api.ts`,
`api/package.json` must also change. Bypass with the `skip api version`
label.
- **API change requires a changelog entry** — if a PR edits
`src/api.ts`, `api/CHANGELOG.md` must also change. Bypass with the `skip
api changelog` label.

## Trade-off

The api package now builds **only in the Linux publish pipeline**. To
build it locally, copy the file first (`cp src/api.ts api/src/main.ts`)
— documented in CONTRIBUTING.md.

## Validation

- `npm run lint` and `tsc -p . --noEmit` pass with the helper folded
into `src/api.ts`.
- The `cp` step produces a byte-identical `api/src/main.ts`.
- `scripts/compare_package_versions.py` verified for both matching (exit
0) and mismatching (exit 1) versions.
- Built old vs. new npm tarballs and ran an isolated consumer against
each (CJS + ESM type-check and runtime smoke): behavior is identical.

---------

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

Author: 3 people

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

@@ -41,3 +41,36 @@ 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)'
+
+      - name: 'Public API changes require a changelog entry'
+        uses: brettcannon/check-for-changed-files@871d7b8b5917a4f6f06662e2262e8ffc51dff6d1 # v1.2.1
+        with:
+          prereq-pattern: 'src/api.ts'
+          file-pattern: 'api/CHANGELOG.md'
+          skip-label: 'skip api changelog'
+          failure-message: 'The public API (${prereq-pattern}) was changed without a changelog entry 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

@@ -89,6 +89,15 @@ This project requires contributors to sign a Contributor License Agreement (CLA)
 
 This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information, see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with questions.
 
+## Public API package (`@vscode/python-environments`)
+
+The npm package under [`api/`](./api) is the public API facade other extensions consume. Its entry point, `api/src/main.ts`, is a **copy** of [`src/api.ts`](./src/api.ts) — the single source of truth — and is **not committed** (see [`api/.gitignore`](./api/.gitignore)).
+
+- 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) and add an entry to [`api/CHANGELOG.md`](./api/CHANGELOG.md) (use the `skip api changelog` label to bypass). When bumping, update both `package.json` files so they stay in sync.
+
 ## Questions or Issues?
 
 - **Questions**: Start a [discussion](https://github.com/microsoft/vscode-python/discussions/categories/q-a)

api/.gitignore

@@ -0,0 +1,4 @@
+# Copied from ../src/api.ts by the publish pipeline (build/azure-pipeline.npm.yml).
+# This is the published package entry point; it is produced at publish time and
+# intentionally NOT committed. src/api.ts is the single source of truth.
+src/main.ts

api/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+All notable changes to the `@vscode/python-environments` API package are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.37.0]
+
+- Aligned the API package version with the Python Environments extension version.

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"
     },