Sync wheel version to git tag; preserve _bin/.gitignore on build

The release version now derives from the git tag: release.yml extracts X.Y.Z
from the vX.Y.Z tag, verifies it matches package.json (fails fast on mismatch),
and passes it as $PKG_VERSION into build_wheels.sh, which stamps it into
__init__.py -- hatch's single source of truth (pyproject declares a dynamic
version). This keeps the GitHub Release tag, the PyPI wheel version, and the
npm version in lockstep instead of the previously hardcoded 0.1.0.

Also make build_wheels.sh clean only the compiled binary from _bin/, preserving
the tracked .gitignore so a local build leaves the tree pristine.

Author: rahlk

.github/workflows/release.yml

@@ -25,6 +25,26 @@ jobs:
       - name: Check out code
         uses: actions/checkout@v4
 
+      # Derive the release version from the tag (vX.Y.Z -> X.Y.Z) and require it
+      # to match package.json. This keeps the PyPI wheel version, the GitHub
+      # Release tag, and the npm version in lockstep -- a mismatch fails fast
+      # rather than silently publishing the wrong version to PyPI.
+      - name: Determine and verify version
+        id: ver
+        run: |
+          pkgjson="$(node -p "require('./package.json').version")"
+          if [[ "${GITHUB_REF}" == refs/tags/* ]]; then
+            version="${GITHUB_REF#refs/tags/v}"
+            if [[ "$version" != "$pkgjson" ]]; then
+              echo "::error::Tag version ($version) != package.json version ($pkgjson). Bump package.json or fix the tag."
+              exit 1
+            fi
+          else
+            version="$pkgjson"   # workflow_dispatch: no tag, fall back to package.json
+          fi
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+          echo ">>> Releasing version $version"
+
       - name: Set up Bun
         uses: oven-sh/setup-bun@v2
         with:
@@ -64,6 +84,8 @@ jobs:
 
       - name: Build platform wheels (cross-compiles every target via Bun)
         working-directory: packaging/python
+        env:
+          PKG_VERSION: ${{ steps.ver.outputs.version }}
         run: ./build_wheels.sh
 
       - name: Extract raw binaries from wheels (for GitHub Release)

packaging/python/README.md

@@ -31,12 +31,26 @@ matrix.
 
 ## Versioning
 
-Keep the version in lockstep across three places:
+The released version comes from the **git tag**. A push of `vX.Y.Z` triggers the
+release workflow, which derives `X.Y.Z` from the tag, verifies it matches this
+repo's `package.json` `version` (failing fast on mismatch), and stamps it into
+`__init__.py` via `$PKG_VERSION` — hatch reads `__version__` as the wheel version
+(`pyproject.toml` declares `dynamic = ["version"]`). So the GitHub Release tag, the
+PyPI wheel version, and the npm `package.json` version are always in lockstep.
 
-- this repo's `package.json` (`version`)
-- `packaging/python/pyproject.toml` (`project.version`) and `__init__.py` (`__version__`)
-- the python-sdk pin in `pyproject.toml`: `[tool.backend-versions] codeanalyzer-typescript`
-  and the `dependencies` entry `codeanalyzer-typescript==<version>`
+To cut a release: bump `package.json` `version`, then push the matching tag, e.g.
+
+```bash
+npm version 0.2.0 --no-git-tag-version   # or edit package.json
+git commit -am "Release v0.2.0" && git tag v0.2.0 && git push --tags
+```
+
+For a **local** wheel build, override the fallback version explicitly:
+`PKG_VERSION=0.2.0 ./build_wheels.sh`.
+
+One thing still tracked by hand: the python-sdk pin — `[tool.backend-versions]
+codeanalyzer-typescript` and the `dependencies` entry
+`codeanalyzer-typescript==<version>` — must be bumped to consume a new release.
 
 ## SDK integration
 

packaging/python/build_wheels.sh

@@ -19,9 +19,33 @@ set -euo pipefail
 
 HERE="$(cd "$(dirname "$0")" && pwd)"
 REPO_ROOT="$(cd "$HERE/../.." && pwd)"          # codeanalyzer-ts repo root (has src/index.ts)
-PKG_VERSION="0.1.0"
+# Version comes from the environment (the release workflow sets it from the git
+# tag); the literal is only a local-dev fallback. It is written into __init__.py,
+# which is hatch's single source of truth for the wheel version.
+PKG_VERSION="${PKG_VERSION:-0.1.0}"
 WHEEL_STEM="codeanalyzer_typescript-${PKG_VERSION}-py3-none-any.whl"
 BIN_DIR="$HERE/src/codeanalyzer_typescript/_bin"
+INIT_PY="$HERE/src/codeanalyzer_typescript/__init__.py"
+
+# Remove built binaries from _bin/ but keep the tracked .gitignore (and the dir),
+# so a local build leaves the working tree pristine.
+clean_bin() { mkdir -p "$BIN_DIR"; find "$BIN_DIR" -mindepth 1 ! -name '.gitignore' -delete; }
+
+# Stamp $PKG_VERSION into __init__.py for the build, restoring the original on
+# exit so the working tree stays pristine (mirrors the _bin cleanup below).
+ORIG_INIT="$(cat "$INIT_PY")"   # $(...) strips the trailing newline; restore re-adds it
+restore_init() { printf '%s\n' "$ORIG_INIT" > "$INIT_PY"; }
+trap restore_init EXIT
+python - "$INIT_PY" "$PKG_VERSION" <<'PY'
+import re, sys
+path, version = sys.argv[1], sys.argv[2]
+text = open(path).read()
+new, n = re.subn(r'__version__ = "[^"]*"', f'__version__ = "{version}"', text)
+if n != 1:
+    raise SystemExit(f"expected exactly one __version__ assignment in {path}, found {n}")
+open(path, "w").write(new)
+print(f">>> stamped __version__ = {version}")
+PY
 
 # "bun --target" : "wheel platform tag"
 TARGETS=(
@@ -46,8 +70,7 @@ for entry in "${TARGETS[@]}"; do
 
   echo ">>> [$target] compiling -> wheel ($plat)"
 
-  rm -rf "$BIN_DIR"
-  mkdir -p "$BIN_DIR"
+  clean_bin
 
   ( cd "$REPO_ROOT" && bun build ./src/index.ts --compile --target="$target" \
       --outfile "$BIN_DIR/codeanalyzer-typescript$ext" )
@@ -58,8 +81,7 @@ for entry in "${TARGETS[@]}"; do
 done
 
 # Clean the working binary so the tree stays pristine.
-rm -rf "$BIN_DIR"
-mkdir -p "$BIN_DIR"
+clean_bin
 
 echo
 echo ">>> Built wheels:"

packaging/python/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "codeanalyzer-typescript"
-version = "0.1.0"
+dynamic = ["version"]
 description = "Prebuilt codeanalyzer-typescript backend binary for CLDK (codellm-devkit)."
 readme = "README.md"
 requires-python = ">=3.8"
@@ -24,6 +24,12 @@ classifiers = [
 Homepage = "https://codellm-devkit.info"
 Repository = "https://github.com/codellm-devkit/codeanalyzer-ts"
 
+# Single source of truth for the package version: __init__.py's __version__.
+# build_wheels.sh overwrites it from $PKG_VERSION (set to the git tag in CI), so a
+# tag of vX.Y.Z always produces a codeanalyzer-typescript==X.Y.Z wheel.
+[tool.hatch.version]
+path = "src/codeanalyzer_typescript/__init__.py"
+
 # The compiled binary lives under _bin/ and is gitignored (it is produced per
 # platform at build time). `artifacts` re-includes it in the wheel anyway --
 # this mirrors how the Java jar is force-included in the python-sdk wheel.