python-wheels.yml

name: Python wheels

# Build, smoke-test, and publish manylinux wheels for the
# `big-code-analysis-py` PyO3 bindings. Phase 7/9 of the umbrella
# Python-bindings effort (#103); see #271 for the rationale.
#
# Design notes captured from the 2026 best-practices research:
#
#   * **manylinux_2_28** is the floor. Rust 1.64+ requires glibc ≥ 2.17
#     (so manylinux2014 is the absolute minimum), but the project's MSRV
#     is 1.94 and the maturin-action default for both x86_64 and aarch64
#     is `2_28`. RHEL/CentOS Stream 8 (glibc 2.28) is the oldest distro
#     that any realistic deployment target still ships, and `2_28`
#     containers carry the modern toolchain we need without forcing
#     consumers off any current LTS.
#
#   * **abi3-py312** produces a single stable-ABI wheel per architecture
#     that works on CPython 3.12, 3.13, 3.14+. PyO3 0.28.3 supports the
#     limited-API flag and a local
#     `cargo check -p big-code-analysis-py --no-default-features
#      --features pyo3/extension-module,pyo3/abi3-py312`
#     builds clean against the bindings' current surface (dict-
#     returning functions, custom exceptions, no generators / no
#     async — the features that would force the non-abi3 fallback).
#     `--no-default-features` is mandatory: the crate's `default =
#     ["pyo3/auto-initialize"]` is documented-incompatible with abi3.
#     The flag is wired through pyproject.toml's
#     `[tool.maturin].features` so `maturin develop` and the wheel
#     build use the identical Cargo feature set — but note that
#     `cargo test --workspace --all-features` continues to use
#     `pyo3/auto-initialize` (not abi3), so the enforcement gate is
#     the `python-test` job in ci.yml + `make pre-commit`, not
#     `cargo test`.
#
#   * **Native ARM runners** (`ubuntu-24.04-arm`) replace QEMU emulation
#     for the aarch64 build. ARM standard runners went GA for private
#     repositories in January 2026 (this repo is private); the cross-
#     build via QEMU was the only path before then but is now an order
#     of magnitude slower with no upside. The maturin-action's
#     `manylinux: 2_28` mode pulls the matching ARM-native manylinux
#     container automatically when the workflow runs on an ARM host.
#
#   * **PyPI Trusted Publishing** (PEP 740) over a long-lived API
#     token. The `publish` job mints a short-lived GitHub OIDC token
#     and exchanges it inside pypa/gh-action-pypi-publish for a one-off
#     PyPI upload credential. Attestations (Sigstore-signed) are
#     generated and uploaded automatically by the action since v1.14.0,
#     so the dedicated `sigstore/gh-action-sigstore-python` step the
#     #271 issue proposed is redundant — keeping it out of this
#     workflow avoids signing the same artefacts twice with conflicting
#     identities. The PyPI side requires a Trusted Publisher entry
#     pointing at this repository + this workflow + the `pypi`
#     deployment environment; the `pypi` env is intentionally distinct
#     from the `release` env used by crates.io publishes in
#     `release.yml` so the two registries' OIDC claims do not overlap.

on:
  push:
    # Narrowed from `v*` to `v[0-9]*` — the original glob matches any
    # tag starting with `v` (e.g. a debugging tag like `verify-grammar-
    # sync` would trigger the publish job and irrevocably push a wheel
    # to PyPI under whatever workspace version the tagged commit
    # carries). `v[0-9]*` requires a digit after the leading `v`, which
    # rules out word-prefixed tags while still accepting `v0.1.0`,
    # `v10.0.0-rc1`, etc. The publish job's `if:` below redundantly
    # checks the same shape so a manual `workflow_dispatch` on a
    # `v[0-9]…` ref still cannot publish.
    tags: ['v[0-9]*']
  pull_request:
    paths:
      - 'big-code-analysis-py/**'
      - '.github/workflows/python-wheels.yml'
  workflow_dispatch:

# Default to read-only; the publish job escalates to id-token: write.
permissions:
  contents: read

# Mirror ci.yml: cancel in-progress runs for ad-hoc refs, but never
# cancel a tag build (release artefacts must complete) or a main build
# (the wheel matrix is the smoke surface for the bindings on push).
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: ${{ github.ref != 'refs/heads/main' && !startsWith(github.ref, 'refs/tags/') }}

# Every `uses:` below is pinned to a commit SHA to neutralise tag-
# rewriting supply-chain attacks. The trailing comment is the tag the
# SHA points at; Dependabot bumps both in lockstep. The SHAs were
# verified against `gh api repos/<owner>/<repo>/git/refs/tags/<tag>`
# (or the action's annotated-tag object) at the time of writing.
env:
  CARGO_TERM_COLOR: always
  CARGO_INCREMENTAL: 0
  CARGO_NET_RETRY: 10
  RUSTUP_MAX_RETRIES: 10
  # Build host's Python — only used to invoke maturin's CLI; the
  # in-container Python that compiles the abi3 wheel comes from the
  # manylinux_2_28 image.
  PYTHON_VERSION_HOST: "3.12"

jobs:
  # Build the wheel matrix. The PR-time gate keeps the cost off
  # Rust-only PRs that happen to touch a path filter neighbour —
  # contributors opt their PR in by applying the `python-wheels` label.
  # Tag pushes and workflow_dispatch always run.
  build:
    name: build (${{ matrix.target }})
    if: >-
      github.event_name != 'pull_request'
      || contains(github.event.pull_request.labels.*.name, 'python-wheels')
    strategy:
      fail-fast: false
      matrix:
        include:
          - target: x86_64-unknown-linux-gnu
            runs-on: ubuntu-latest
            arch: x86_64
          - target: aarch64-unknown-linux-gnu
            runs-on: ubuntu-24.04-arm
            arch: aarch64
    runs-on: ${{ matrix.runs-on }}
    timeout-minutes: 45
    steps:
      # No submodules — the bindings' fixtures are in-tree.
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 1
          submodules: false

      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
        with:
          python-version: ${{ env.PYTHON_VERSION_HOST }}

      # A clean checkout cannot expose accidentally packaged bytecode.
      - name: Populate source bytecode caches
        run: python -m compileall -q big-code-analysis-py/python/big_code_analysis

      # maturin-action pulls the manylinux_2_28 container that matches
      # ${{ matrix.target }} and prepends `--manylinux 2_28` to the
      # maturin invocation (maturin's `--manylinux` is an alias of
      # `--compatibility` with `ArgAction::Append`). The action's
      # `manylinux:` input is the only place we set the platform tag;
      # adding a redundant `--compatibility manylinux_2_28` to `args:`
      # would double-append the value and either error or emit a
      # multi-tag wheel filename that the verification step rejects.
      # `--strip` removes debug symbols (the .pyi stub carries the
      # public name table, so IDE support is unaffected). `--locked`
      # forces cargo to honour the workspace Cargo.lock byte-for-byte
      # so the wheel's transitive-dep versions are reproducible from
      # the tagged commit — matching the `cargo publish --locked`
      # contract `release.yml` uses for the crates.io publishes.
      - name: Build wheel (manylinux_2_28 / ${{ matrix.arch }} / abi3)
        uses: PyO3/maturin-action@e83996d129638aa358a18fbd1dfb82f0b0fb5d3b # v1.51.0
        with:
          working-directory: big-code-analysis-py
          target: ${{ matrix.target }}
          manylinux: "2_28"
          args: --release --strip --locked --out dist

      # Inspect the produced filename so an abi3 / manylinux /
      # architecture regression shows up here instead of at PyPI
      # upload time. The glob is scoped to `${{ matrix.arch }}` so a
      # wrong-arch wheel (e.g. maturin-action silently ignoring
      # `target:`) produced on this runner does NOT pass: the
      # aarch64 leg refuses an x86_64 wheel and vice versa. The
      # `cp312-abi3` segment catches per-version wheels emitted when
      # the abi3 feature drops out of pyproject.toml.
      - name: Verify wheel is abi3 + manylinux_2_28 / ${{ matrix.arch }}
        working-directory: big-code-analysis-py
        env:
          EXPECTED_ARCH: ${{ matrix.arch }}
        run: |
          set -euo pipefail
          ls -la dist/
          shopt -s nullglob
          matches=(dist/*cp312-abi3-manylinux_2_28_"${EXPECTED_ARCH}".whl)
          if [[ ${#matches[@]} -eq 0 ]]; then
            echo "::error::No wheel matches cp312-abi3-manylinux_2_28_${EXPECTED_ARCH}.whl in dist/"
            ls dist/
            exit 1
          fi
          # Defensive: refuse to upload if the directory holds an
          # extra wheel for the *other* arch — that would mean the
          # cross-build accidentally produced two wheels and the
          # artifact upload would carry both, polluting the publish
          # job's `pattern: wheels-*` merge.
          extras=(dist/*.whl)
          if [[ ${#extras[@]} -ne ${#matches[@]} ]]; then
            echo "::error::dist/ contains wheels other than ${EXPECTED_ARCH}; refusing to upload"
            ls dist/
            exit 1
          fi
          python - "${matches[@]}" <<'PY'
          import sys
          import zipfile
          from pathlib import PurePosixPath

          for path in sys.argv[1:]:
              with zipfile.ZipFile(path) as wheel:
                  cached = [
                      name for name in wheel.namelist()
                      if "__pycache__" in PurePosixPath(name).parts or name.endswith(".pyc")
                  ]
              if cached:
                  raise SystemExit(f"{path} contains bytecode caches: {cached}")
          PY

      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
        with:
          name: wheels-${{ matrix.arch }}
          path: big-code-analysis-py/dist/*.whl
          if-no-files-found: error

  # Source distribution. Required by PyPI as a fallback for niche
  # architectures and as a reproducibility anchor (the wheel is binary;
  # the sdist captures the exact source tree the wheel was built from).
  sdist:
    name: sdist
    if: >-
      github.event_name != 'pull_request'
      || contains(github.event.pull_request.labels.*.name, 'python-wheels')
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 1
          submodules: false

      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
        with:
          python-version: ${{ env.PYTHON_VERSION_HOST }}

      # `maturin sdist` only bundles the source tree (it does not
      # compile, so `--locked` is rejected by the subcommand). The
      # workspace `Cargo.lock` is included in the tarball anyway, so a
      # downstream `pip install --no-binary :all:` rebuild from the
      # sdist resolves to the same transitive-dep versions the
      # published wheel was built against — the lockfile travels with
      # the source.
      - name: Build sdist
        uses: PyO3/maturin-action@e83996d129638aa358a18fbd1dfb82f0b0fb5d3b # v1.51.0
        with:
          working-directory: big-code-analysis-py
          command: sdist
          args: --out dist

      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
        with:
          name: sdist
          path: big-code-analysis-py/dist/*.tar.gz
          if-no-files-found: error

  # Smoke test: pull the built wheel onto a clean runner of the same
  # architecture, install it from the dist directory (no PyPI round-
  # trip), and exercise enough of the API to catch dynamic-linker
  # failures (`ImportError`, missing symbols) and trivial regressions
  # in the JSON output shape. Both Python 3.12 and 3.13 are exercised
  # so the abi3 forward-compatibility claim is verified end-to-end —
  # an abi3 wheel that loads on the build's 3.12 but not the runner's
  # 3.13 is the most plausible silent regression in this matrix.
  smoke-test:
    name: smoke-test (${{ matrix.arch }}, py${{ matrix.python }})
    needs: build
    strategy:
      fail-fast: false
      matrix:
        include:
          - arch: x86_64
            runs-on: ubuntu-latest
          - arch: aarch64
            runs-on: ubuntu-24.04-arm
        python: ["3.12", "3.13"]
    runs-on: ${{ matrix.runs-on }}
    timeout-minutes: 15
    steps:
      # Sparse, submodule-free checkout of just the smoke harness. The
      # smoke step runs `scripts/smoke/lib_wheel_smoke.py` against the
      # downloaded wheel (#995 — extracted from the former inline heredoc
      # so the assertions are lintable and also run per-PR via
      # smoke-dryrun.yml). `sparse-checkout` + `submodules: false` keep
      # the aarch64 native-ARM clone cheap: the wall-clock cost this job
      # historically skipped was the full clone's LFS-adjacent submodules,
      # not the handful of files under scripts/smoke.
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          sparse-checkout: scripts/smoke
          submodules: false
      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
        with:
          python-version: ${{ matrix.python }}

      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
        with:
          name: wheels-${{ matrix.arch }}
          path: dist

      - name: Install wheel
        run: |
          set -euo pipefail
          ls -la dist/
          # Install the just-built wheel by path; the build job's verify
          # step guarantees every wheel in dist/ matches this arch's
          # abi3 pattern (and pip would fail loudly on a duplicate), and
          # --no-index makes accidental PyPI fallback (e.g. when the
          # wheel name does not match the current interpreter) fail
          # loudly rather than silently install a stale published
          # version. --no-deps is a no-op today (the wheel has zero
          # Python runtime deps) but keeps a future dep addition from
          # being resolved unpinned here (OpenSSF Scorecard
          # Pinned-Dependencies).
          python -m pip install --no-index --no-deps dist/*.whl

      # Exercise the public API surface that #103 enumerates:
      # analyze_source returns a dict, flatten_spaces yields function
      # records, to_sarif emits SARIF JSON, language_for_file resolves
      # extensions. If any of these regress the smoke fails before
      # the wheel can publish. The assertions are deliberately
      # VALUE-bearing, not just shape-bearing — see the per-API
      # `_check_*` helpers in scripts/smoke/lib_wheel_smoke.py.
      - name: Import + analyse smoke
        env:
          # Force unbuffered stdout so failure assertions show up
          # immediately in the action log instead of after the python
          # process has been torn down.
          PYTHONUNBUFFERED: "1"
        # The assertions live in a checked-in, mypy-strict, ruff-linted
        # script (#995) so a binding rename/serialization change reds a
        # PR via smoke-dryrun.yml instead of only this tag-gated job.
        run: python scripts/smoke/lib_wheel_smoke.py

      # pip-audit deliberately NOT run here. The pre-publish wheel
      # has zero Python runtime deps (the binary surface is the
      # PyO3 extension only) and pip-audit's only useful pre-publish
      # target — "is the just-built version vulnerable?" — cannot
      # be answered because that version is not yet on PyPI. A
      # naive `python -m pip install pip-audit && pip-audit` would
      # also pollute the smoke venv with pip-audit's transitive
      # deps (requests, packaging, cyclonedx-python-lib, …) and
      # red the gate on every CVE filed against any of them. The
      # right place for a dependency audit is a post-publish job
      # against the actual PyPI listing once the wheel acquires
      # runtime deps; opening that as a follow-up.

  # Aggregate gate so branch protection can require a single check
  # name regardless of how the matrix expands. Mirrors the `ci` job in
  # ci.yml — with one wrinkle. Unlike ci.yml's `ci` job, every
  # dependency here is gated on the `python-wheels` PR label, so on a
  # PR without the label all needs resolve to `skipped`. The naive
  # `contains(needs.*.result, 'failure') || ... 'cancelled')` from
  # ci.yml's pattern would then return false and the aggregate would
  # report success despite zero wheels having been built — defeating
  # the gate. The predicate is widened to also fail on `skipped` so
  # an unlabelled PR-time run does not silently green-tick the
  # required check.
  #
  # Tag pushes and `workflow_dispatch` runs always exercise every
  # leg (no `if:` gating on those events), so widening the predicate
  # does not over-flag those paths.
  wheels:
    name: wheels
    if: always()
    needs:
      - build
      - sdist
      - smoke-test
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
      - name: Fail if any dependency did not succeed
        # `skipped` only counts as a failure when the build legs were
        # *meant* to run — tag pushes, workflow_dispatch, or a labelled
        # PR. On an unlabelled PR the legs are intentionally skipped, so
        # treating that skip as a failure would red-X every PR that
        # brushes the path filter for no signal (the wheel matrix is
        # opt-in via the `python-wheels` label). The skipped-is-green
        # required-check loophole this clause guards against still
        # applies on the runs that are supposed to build.
        if: >-
          contains(needs.*.result, 'failure')
          || contains(needs.*.result, 'cancelled')
          || (
            contains(needs.*.result, 'skipped')
            && (
              github.event_name != 'pull_request'
              || contains(github.event.pull_request.labels.*.name, 'python-wheels')
            )
          )
        run: exit 1

  # PyPI publish — only on a `v*` tag push. The `pypi` deployment
  # environment binds the OIDC `environment` claim that the PyPI
  # Trusted Publisher matches against; protection rules on the
  # environment (required reviewers, allowed tag patterns) are the
  # right place to add a manual approval gate, not the workflow.
  #
  # Trusted Publisher must be registered on PyPI before the first
  # release — see RELEASING.md → "PyPI Trusted Publisher setup".
  # The first tagged release after registration is the canonical
  # end-to-end test of the OIDC handshake; there is no static token
  # to fall back on.
  publish:
    name: publish to PyPI
    needs: [build, sdist, smoke-test]
    # The `on.push.tags: ['v[0-9]*']` filter above is the primary
    # gate: GitHub only fires this workflow on tag pushes that match
    # the numeric-prefix glob, so word-prefixed tags like
    # `verify-grammar-sync` cannot reach the publish job. The
    # `event_name == 'push'` belt-and-braces excludes
    # `workflow_dispatch` runs (which can be triggered against any
    # ref, including a `v[0-9]…` tag, and would otherwise satisfy
    # the `startsWith` check). GHA expressions do not have a
    # substring/regex operator, so re-validating the digit-after-v
    # constraint inside the `if:` would require an unwieldy
    # ten-clause disjunction — the `on:` filter is the source of
    # truth.
    #
    # Prerelease tags (`v0.1.0-rc1`, `-beta2`, `-alpha3`, …) are
    # explicitly NOT published — matching the policy `release.yml`
    # establishes for crates.io publishes (its "Cutting a pre-
    # release" section). The two registries' publishing posture must
    # stay aligned so a single tag does not simultaneously land a
    # prerelease on PyPI and skip crates.io. The `contains` checks
    # below cover the three suffixes the wider release pipeline
    # recognises; any tag containing one of them in its ref name
    # skips publish and only exercises the build + smoke matrix.
    if: >-
      github.event_name == 'push'
      && startsWith(github.ref, 'refs/tags/v')
      && !contains(github.ref, '-rc')
      && !contains(github.ref, '-beta')
      && !contains(github.ref, '-alpha')
    runs-on: ubuntu-latest
    environment:
      name: pypi
      url: https://pypi.org/project/big-code-analysis/
    permissions:
      # Workflow-level `contents: read` does NOT cascade into a job
      # that declares its own `permissions:` block — the block
      # replaces the default rather than augmenting it. Restate
      # `contents: read` so any future step here (e.g. an
      # `actions/checkout` to read CHANGELOG.md for release notes)
      # has the access the workflow-level default would have
      # otherwise granted.
      contents: read
      # Trusted publishing exchanges this OIDC token for a one-off
      # PyPI upload credential; the long-lived `PYPI_API_TOKEN`
      # secret pattern this replaces is explicitly forbidden by #271.
      id-token: write
      # attestations: write is implied by id-token: write at the
      # workflow level, but spelling it out keeps the PEP 740
      # attestation pipeline obvious to a reviewer.
      attestations: write
    steps:
      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
        with:
          pattern: wheels-*
          path: dist
          merge-multiple: true

      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
        with:
          name: sdist
          path: dist

      - name: Inventory artefacts
        run: |
          set -euo pipefail
          ls -la dist/
          # Defensive: refuse to publish unless every architecture's
          # wheel arrived (a download-artifact silently dropping one
          # leg would otherwise publish a half-matrix release). The
          # `::error::` annotations surface the failure in the GH
          # Actions UI summary instead of being buried in stderr.
          shopt -s nullglob
          require() {
            local label=$1
            shift
            local matches=("$@")
            if [[ ${#matches[@]} -eq 0 ]]; then
              echo "::error::Missing expected artefact: ${label}"
              exit 1
            fi
          }
          require "cp312-abi3 / x86_64 wheel" dist/*-cp312-abi3-manylinux_2_28_x86_64.whl
          require "cp312-abi3 / aarch64 wheel" dist/*-cp312-abi3-manylinux_2_28_aarch64.whl
          require "sdist tarball" dist/*.tar.gz

      # pypa/gh-action-pypi-publish v1.14.0 turns on PEP 740 Sigstore
      # attestations by default when invoked with id-token: write. No
      # username / password / api-token inputs — the trusted-publisher
      # exchange is the only auth path, and a missing TP registration
      # surfaces here as an obvious HTTP 403 rather than a silent
      # fallback to a token that does not exist.
      - name: Publish to PyPI
        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
        with:
          packages-dir: dist
          # Explicit even though it is the default; the assertion is
          # that we never published from anywhere except a verified
          # OIDC-authenticated job.
          attestations: true