Generate published API entry point from src/api.ts

[edvilme]

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.

[edvilme]

Optional: I think this would be helpful, but could understand if we would rather have separate versions of the API and the extension to better identify breaking changes.

[Copilot]

Pull request overview

This PR makes src/api.ts the single source of truth for the published @vscode/python-environments API by generating api/src/main.ts at publish time instead of committing a drift-prone duplicate, and adds CI checks to keep the published package version aligned with the extension version.

Changes:

• Folded the publish-only runtime helper (PythonEnvironments.api() and EXTENSION_ID) into src/api.ts and removed the committed api/src/main.ts copy.
• Updated the npm publish pipeline to copy src/api.ts → api/src/main.ts before compiling/packing the API package.
• Added CI enforcement for API version bumping + version parity between package.json and api/package.json.

Reviewed changes

Copilot reviewed 8 out of 9 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/api.ts	Adds the runtime helper + extension ID to the canonical API surface.
api/src/main.ts	Removes the committed duplicate API entry point (now generated).
api/.gitignore	Ignores generated api/src/main.ts to prevent reintroducing duplication.
build/azure-pipeline.npm.yml	Copies src/api.ts into the API package during the publish build.
api/package.json	Bumps API package version to stay in lock-step with the extension.
api/package-lock.json	Updates lockfile version metadata to match the API package bump.
scripts/compare_package_versions.py	Adds a CI script to enforce extension/package version parity.
CONTRIBUTING.md	Documents the new “copy at publish time” model and versioning expectations.
.github/workflows/pr-file-check.yml	Enforces API version bump on src/api.ts edits and checks version parity.

Files not reviewed (1)

• api/package-lock.json: Generated file

[Copilot]

Pull request overview

Copilot reviewed 9 out of 10 changed files in this pull request and generated 1 comment.

Files not reviewed (1)

• api/package-lock.json: Generated file