Skip to content

feat(ci): publish bca CLI to PyPI as pip wheel#504

Merged
dekobon merged 3 commits into
mainfrom
feat/cli-pypi-wheels
Jun 4, 2026
Merged

feat(ci): publish bca CLI to PyPI as pip wheel#504
dekobon merged 3 commits into
mainfrom
feat/cli-pypi-wheels

Conversation

@dekobon
Copy link
Copy Markdown
Owner

@dekobon dekobon commented Jun 4, 2026

Summary

Makes the bca CLI pip-installable: pip install big-code-analysis-cli
drops the compiled bca binary onto PATH (no Rust toolchain), the way
pip install ruff installs the ruff command. Closes #408.

The PyPI distribution name is big-code-analysis-cli while the
installed command stays bca — distinct from the importable library
bindings published as big-code-analysis. The naming split is stated
explicitly in every doc a user or maintainer touches.

What's here

  • big-code-analysis-cli/pyproject.toml — maturin -b bin config:
    bindings = "bin", dynamic version from the workspace Cargo.toml
    (lockstep), license-files for LICENSE + THIRD-PARTY-LICENSES-bca.md
    .dist-info/licenses/, globbed man-page include. No
    [tool.maturin] features needed — the crate already pins all-languages
    (feat(lib): per-language Cargo features for grammar selection #252), so the bin build carries every grammar.
  • .github/workflows/python-cli-wheels.yml — standalone, modeled on
    python-wheels.yml: numeric-tag trigger, opt-in python-cli-wheels PR
    label, build matrix (Linux manylinux_2_28 x86_64/aarch64, macOS
    x86_64/arm64, Windows x86_64), per-leg cargo-about TPL staging, arch-
    specific wheel verification, clean-env smoke (install + bca --version
    tag-parity + list-metrics + cross-language parse), aggregate gate, and
    PyPI Trusted Publishing in a distinct pypi-cli environment.
  • .gitignore — ignores the workflow-staged artefacts.
  • Docs — CLI README, book commands/README.md, CHANGELOG, and
    RELEASING.md (one-time TP setup, per-release flow, pre-tag checklist).

Local validation (maturin 1.13.3)

Built the -b bin wheel and confirmed on Linux x86_64:

  • bca installs to <env>/bin/bca (.data/scripts/bca); bca --version
    1.1.0 (lockstep with workspace).
  • Python, Rust, and TypeScript all parse (cyclomatic.sum = 3.0
    each) → all-languages grammar set present.
  • LICENSE + THIRD-PARTY-LICENSES-bca.md in .dist-info/licenses/;
    License-File: metadata recorded; bca-web.1 correctly excluded.
  • maturin sdist succeeds on a clean tree (globs/license-files skip
    absent staged files — no build breakage).

make pre-commit is green (cargo trio, udeps, man-page drift gate,
self-scan, py-test, markdown/TOML/actionlint). The change set is
CI/packaging/docs only — no Rust source touched.

Release-gated follow-ups (maintainer action, tracked in #408)

These cannot be validated until release time:

  • One-time PyPI Trusted Publisher registration for
    big-code-analysis-cli (workflow python-cli-wheels.yml, env
    pypi-cli) + create the pypi-cli GitHub environment.
  • Create the python-cli-wheels PR label (so the matrix runs on PRs).
  • First v* tag validates the cross-platform matrix + OIDC publish
    end-to-end (macOS x86_64 is cross-built on the arm64 runner — the only
    leg not exercisable locally).

Notes for reviewers

This PR has been through /review, /audit-tests, and a high-recall
/code-review pass. The review findings (SIGPIPE | head, loose macOS
arch verify, unpinned toolchain, prerelease-guard/doc mismatch, missing
version-parity assertion) are fixed in the fix(ci): commit.

dekobon added 3 commits June 3, 2026 15:40
Add a standalone python-cli-wheels.yml workflow plus a -b bin
pyproject.toml so `pip install big-code-analysis-cli` drops the
compiled `bca` binary onto PATH (no Rust toolchain), the way
`pip install ruff` installs `ruff`.

The dist name (big-code-analysis-cli) differs from the installed
command (bca) and from the importable library bindings
(big-code-analysis); README, book, and CHANGELOG state the split
explicitly.

Mirrors python-wheels.yml: numeric-tag trigger, opt-in PR label,
aggregate gate, PyPI Trusted Publishing in a distinct `pypi-cli`
environment. Differs in shipping a py3-none-<platform> bin wheel
(no abi3 / no per-Python matrix) across Linux manylinux_2_28
(x86_64/aarch64), macOS (x86_64/arm64), and Windows (x86_64).

The CLI crate already pins all-languages (#252), so the bin build
carries every grammar with no maturin feature wiring. Per-binary
THIRD-PARTY-LICENSES-bca.md (cargo-about) + LICENSE ride in
.dist-info/licenses/ via [project].license-files; man pages are
bundled via [tool.maturin] include (globbed so clean builds and
sdist still work). Staged artefacts are gitignored.

RELEASING.md documents the one-time PyPI Trusted Publisher and
pypi-cli environment setup.

Fixes #408
The release narrative described only release.yml. Note that the same
v* tag also fires python-wheels.yml and python-cli-wheels.yml in
parallel, that they publish in lockstep on every bump, that
prerelease tags skip the PyPI publish (matching crates.io), and add
a post-release step to verify both wheels landed.

Fixes #408
- smoke-test: replace `bca list-metrics names | head -n1` with a
  redirect to /dev/null — the pipe SIGPIPEs the producer under
  pipefail (the anti-pattern release.yml documents).
- smoke-test: implement the version-parity assertion the comment
  promised — on a tag build, assert `bca --version` contains the tag
  version; skip on PR/dispatch (no tag, no checkout).
- build/verify: make the macOS per-leg wheel check arch-specific
  (`macosx_*_x86_64` / `macosx_*_arm64`) so a cross-build emitting the
  host arch fails at the leg, not only at the publish inventory.
- build: pin the host toolchain (RUST_TOOLCHAIN 1.94.0, matching
  release.yml) so macOS/Windows wheel binaries are reproducible
  instead of tracking a floating stable.
- publish: widen the prerelease guard to `!contains(github.ref, '-')`
  to match release.yml's `*-*` rule exactly, so a single tag cannot
  land a prerelease on PyPI while skipping crates.io; RELEASING.md
  updated to describe the actual guards.
- fix stale "venv" wording in smoke-test comments (no venv is created).

Fixes #408
@dekobon dekobon merged commit 63c9091 into main Jun 4, 2026
43 of 44 checks passed
@dekobon dekobon deleted the feat/cli-pypi-wheels branch June 4, 2026 01:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat(cli): publish the bca CLI to PyPI as a pip-installable binary

1 participant