From db8663124cafc14917c9c3a3205d2d3fca393094 Mon Sep 17 00:00:00 2001 From: shriraj pawar Date: Fri, 17 Apr 2026 11:26:52 +0530 Subject: [PATCH] fix(chore): migrating from tox to just for better devex --- .github/PULL_REQUEST_TEMPLATE.md | 4 +- .github/workflows/ci.yml | 47 +++++++++++------ CONTRIBUTING.md | 9 ++-- Justfile | 72 +++++++++++++++++++++++++ README.md | 88 ++++++++++++++++++++---------- tox.ini | 91 +++++++++++++++----------------- 6 files changed, 214 insertions(+), 97 deletions(-) create mode 100644 Justfile diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 355f66900..59a7f36aa 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -7,9 +7,9 @@ ## ✅ Checklist -- [ ] Ran `tox` checks to avoid unnecessary CI fails: +- [ ] Ran local quality checks to avoid unnecessary CI fails: ```console - uvx tox + just check ``` - [ ] Considered adding appropriate tests for the changes. - [ ] Considered updating the online docs in the [./docs/](/leanEthereum/leanSpec/tree/main/docs/) directory. diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 7053a0a2d..a33be85ef 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -37,8 +37,13 @@ jobs: enable-cache: true cache-dependency-glob: "pyproject.toml" - - name: Run all quality checks via tox - run: uvx tox -e all-checks + - name: Install just + uses: taiki-e/install-action@v2 + with: + tool: just + + - name: Run all quality checks + run: just check test: name: Tests - Python ${{ matrix.python-version }} on ${{ matrix.os }} @@ -63,8 +68,13 @@ jobs: enable-cache: true cache-dependency-glob: "pyproject.toml" - - name: Run tests via tox - run: uvx tox -e pytest + - name: Install just + uses: taiki-e/install-action@v2 + with: + tool: just + + - name: Run tests + run: just test coverage-gate: name: Coverage gate - Python 3.12 @@ -84,8 +94,13 @@ jobs: enable-cache: true cache-dependency-glob: "pyproject.toml" + - name: Install just + uses: taiki-e/install-action@v2 + with: + tool: just + - name: Run tests with coverage gate - run: uvx tox -e pytest-cov-gate + run: just test-cov-gate fill-tests: name: Fill test fixtures - Python 3.14 @@ -105,11 +120,13 @@ jobs: enable-cache: true cache-dependency-glob: "pyproject.toml" - - name: Sync dependencies - run: uv sync --no-progress + - name: Install just + uses: taiki-e/install-action@v2 + with: + tool: just - name: Fill test fixtures - run: uv run fill --fork=Devnet --clean -n auto + run: just fill interop-tests: name: Interop tests - Multi-node consensus @@ -130,14 +147,12 @@ jobs: enable-cache: true cache-dependency-glob: "pyproject.toml" + - name: Install just + uses: taiki-e/install-action@v2 + with: + tool: just + - name: Run interop tests - run: | - uv run pytest tests/interop/ \ - -v \ - --no-cov \ - --timeout=120 \ - -x \ - --tb=short \ - --log-cli-level=INFO + run: just interop env: LEAN_ENV: test diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6b7a0b657..6f8183433 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,9 +5,10 @@ 1. Fork and clone the repository 2. Install dependencies: `uv sync` 3. Make your changes -4. Run checks: `uvx tox -e all-checks` -5. Run tests: `uvx tox -e pytest` -6. Submit a pull request +4. Install `just`: `uv tool install just-bin` +5. Run checks: `just check` +6. Run tests: `just test` +7. Submit a pull request ## Pull Request Guidelines @@ -22,7 +23,7 @@ - **Type hints**: Required for all functions and methods - **Docstrings**: Use Google style for public APIs - **Line length**: 100 characters (enforced by ruff) -- **Formatting**: Run `uvx tox -e fix` to auto-format +- **Formatting**: Run `just fix` to auto-format ## Adding New Subspecifications diff --git a/Justfile b/Justfile new file mode 100644 index 000000000..e79806c52 --- /dev/null +++ b/Justfile @@ -0,0 +1,72 @@ +set positional-arguments := true + +alias help := default + +[default] +default: + @just --list + +[group('quality')] +check: lint typecheck spellcheck mdformat + +[group('quality')] +lint *args: + uv run --group lint ruff check --no-fix --show-fixes "$@" + +[group('quality')] +format *args: + uv run --group lint ruff format "$@" + +[group('quality')] +fix: + uv run --group lint ruff check --fix + uv run --group lint ruff format + uv run --group docs mdformat docs/ + +[group('quality')] +typecheck *args: + uv run --group lint ty check "$@" + +[group('quality')] +spellcheck *args: + uv run --group lint codespell src tests packages docs README.md CLAUDE.md --skip="*.lock,*.svg,.git,__pycache__,.pytest_cache,tests/lean_spec/snappy/testdata" --ignore-words=.codespell-ignore-words.txt "$@" + +[group('quality')] +mdformat *args: + uv run --group docs mdformat --check docs/ "$@" + +[group('tests')] +test *args: + uv run --group test pytest tests -n auto --maxprocesses=10 --durations=10 --dist=worksteal "$@" + +[group('tests')] +test-cov *args: + uv run --group test pytest --cov --cov-report=html --cov-report=term "$@" + +[group('tests')] +test-cov-gate *args: + uv run --group test pytest --cov --cov-report=term-missing --cov-fail-under=80 "$@" + +[group('tests')] +test-consensus *args: + uv run --group test pytest -n auto --maxprocesses=10 --durations=10 --dist=worksteal tests/lean_spec/subspecs/containers tests/lean_spec/subspecs/forkchoice tests/lean_spec/subspecs/networking "$@" + +[group('tests')] +fill *args: + uv run --group test fill --fork=Devnet --clean -n auto "$@" + +[group('tests')] +apitest server_url *args: + uv run --group test apitest "{{server_url}}" "$@" + +[group('tests')] +interop *args: + uv run --group test pytest tests/interop/ -v --no-cov --timeout=120 -x --tb=short --log-cli-level=INFO "$@" + +[group('docs')] +docs *args: + uv run --group docs mkdocs build "$@" + +[group('docs')] +docs-serve *args: + uv run --group docs mkdocs serve "$@" diff --git a/README.md b/README.md index 657f019ae..2e9db996b 100644 --- a/README.md +++ b/README.md @@ -20,6 +20,20 @@ The Lean Ethereum protocol specifications and cryptographic subspecifications. curl -LsSf https://astral.sh/uv/install.sh | sh ```` +#### Installing just + +[`just`](https://just.systems/) is the task runner used for common developer +workflows in this repository. + +```bash +# Recommended cross-platform install +uv tool install just-bin + +# Alternatives +brew install just +apt install just +``` + #### Installing Python 3.12+ This project requires Python 3.12 or later and should be installed via `uv`: @@ -57,8 +71,11 @@ cd leanSpec # Install and sync project and dev dependencies, using `uv.lock` versions uv sync +# See the available repo tasks +just + # Run tests to verify setup -uv run pytest +just test ``` ### Project Structure @@ -97,7 +114,10 @@ uv sync ### Running Tests ```bash -# Run all tests from workspace root +# Run the default test suite +just test + +# Run all tests from workspace root without just uv run pytest # Run tests in parallel, utilizing all available CPU cores @@ -121,37 +141,51 @@ uv run fill --clean --fork=devnet --scheme=prod # Run API conformance tests against an external client implementation # Usage: uv run apitest [pytest-args] uv run apitest http://localhost:5052 + +# Same API conformance test through the task runner +just apitest http://localhost:5052 ``` ### Code Quality ```bash +# Run the full quality gate +just check + # Check code style and errors -uv run ruff check +just lint # Auto-fix issues -uv run ruff check --fix +just fix # Format code -uv run ruff format +just format # Type checking -uv run ty check +just typecheck ``` -### Using Tox for Comprehensive Checks +### Using just for Common Tasks -You can use `tox` with `uvx`, which: -* Creates a temporary environment just for `tox` -* Doesn't require `uv sync` first -* Uses `tox-uv` for faster dependency installation +Run `just` with no arguments to see the available recipes. `just` is the +primary command surface for contributors, while raw `uv run ...` commands remain +available when you want to invoke tools directly. ```bash -# Run specific environment, like "all quality checks" (lint, typecheck, spellcheck) -uvx tox -e all-checks +# List available tasks +just + +# Run quality checks +just check + +# Run tests +just test + +# Build documentation +just docs -# Run all tox environments (all checks + tests + docs) -uvx tox +# Generate consensus fixtures +just fill ``` ### Documentation @@ -210,7 +244,7 @@ def test_withdrawal_amount_above_uint64_max(): - **uv**: Fast Python package manager - like npm/yarn but for Python - **ruff**: Linter and formatter - **ty**: Type checker -- **tox**: Automation tool for running tests across multiple environments (used via `uvx`) +- **just**: Task runner for repository workflows such as checks, tests, docs, and fixture generation - **mkdocs**: Documentation generator - write docs in Markdown, serve them locally ## Common Commands Reference @@ -218,16 +252,16 @@ def test_withdrawal_amount_above_uint64_max(): | Task | Command | |-----------------------------------------------|--------------------------------------------------------| | Install and sync project and dev dependencies | `uv sync` | -| Run tests | `uv run pytest ...` | -| Format code | `uv run ruff format` | -| Lint code | `uv run ruff check` | -| Fix lint errors | `uv run ruff check --fix` | -| Type check | `uv run ty check` | -| Build docs | `uv run mkdocs build` | -| Serve docs | `uv run mkdocs serve` | -| Run everything (checks + tests + docs) | `uvx tox` | -| Run all quality checks (no tests/docs) | `uvx tox -e all-checks` | -| Test external client API conformance | `uv run apitest http://localhost:5052` | +| List repo tasks | `just` | +| Run quality checks | `just check` | +| Run tests | `just test` | +| Format code | `just format` | +| Fix lint and formatting | `just fix` | +| Type check | `just typecheck` | +| Build docs | `just docs` | +| Serve docs | `just docs-serve` | +| Generate consensus fixtures | `just fill` | +| Test external client API conformance | `just apitest http://localhost:5052` | | Run consensus node | `uv run python -m lean_spec --genesis config.yaml` | | Build Docker test image | `docker build -t lean-spec:test .` | | Build Docker node image | `docker build --target node -t lean-spec:node .` | @@ -265,7 +299,7 @@ docker run --rm lean-spec:test # Run tests in parallel docker run --rm lean-spec:test uv run pytest -n auto -# Run the fill command +# Run the fill command directly docker run --rm lean-spec:test uv run fill --clean --fork=devnet ``` diff --git a/tox.ini b/tox.ini index ed9aa3828..71e8d1f5b 100644 --- a/tox.ini +++ b/tox.ini @@ -1,81 +1,76 @@ [tox] min_version = 4.0 -requires = - tox >=4.32.0,<5 - tox-uv >=1.29 -env_list = - # defines what runs when `uvx tox` is executed with no `-e` argument - all-checks - pytest - docs-build +env_list = all-checks [testenv] -uv_python = >=3.12 -package = editable -runner = uv-venv-lock-runner -set_env = - NUMBA_DISABLE_JIT = 1 +description = leanSpec now uses just for task orchestration +skip_install = true +allowlist_externals = printf, false +commands = + printf '\n\033[1m leanSpec has migrated from tox to just.\033[0m\n\n Install just with:\n uv tool install just-bin\n\n Run \033[1mjust\033[0m to see available recipes.\n\n' + false [testenv:all-checks] -description = Run all quality checks (lint, typecheck, spellcheck, mdformat) commands = - {[testenv:lint]commands} - {[testenv:typecheck]commands} - {[testenv:spellcheck]commands} - {[testenv:mdformat]commands} + printf '\n\033[1m leanSpec has migrated from tox to just.\033[0m\n\n Use:\n \033[1mjust check\033[0m\n\n' + false [testenv:lint] -description = Lint and code formatting checks (ruff) commands = - ruff check --no-fix --show-fixes - ruff format --check + printf '\n\033[1m leanSpec has migrated from tox to just.\033[0m\n\n Use:\n \033[1mjust lint\033[0m\n\n' + false [testenv:fix] -description = Auto-fix linting and formatting issues (ruff) commands = - ruff check --fix - ruff format + printf '\n\033[1m leanSpec has migrated from tox to just.\033[0m\n\n Use:\n \033[1mjust fix\033[0m\n\n' + false [testenv:typecheck] -description = Run type checking (ty) -commands = ty check +commands = + printf '\n\033[1m leanSpec has migrated from tox to just.\033[0m\n\n Use:\n \033[1mjust typecheck\033[0m\n\n' + false [testenv:spellcheck] -description = Run spell checking (codespell) -commands = codespell src tests packages docs README.md CLAUDE.md --skip="*.lock,*.svg,.git,__pycache__,.pytest_cache,tests/lean_spec/snappy/testdata" --ignore-words=.codespell-ignore-words.txt +commands = + printf '\n\033[1m leanSpec has migrated from tox to just.\033[0m\n\n Use:\n \033[1mjust spellcheck\033[0m\n\n' + false [testenv:mdformat] -description = Check markdown formatting for docs (mdformat) -commands = mdformat docs/ +commands = + printf '\n\033[1m leanSpec has migrated from tox to just.\033[0m\n\n Use:\n \033[1mjust mdformat\033[0m\n\n' + false [testenv:fill] -description = Generate consensus layer test fixtures -commands = fill --fork=Devnet --clean -n auto {posargs} +commands = + printf '\n\033[1m leanSpec has migrated from tox to just.\033[0m\n\n Use:\n \033[1mjust fill\033[0m\n\n' + false [testenv:pytest] -description = Run tests (pytest) -# parallelize with `auto` but keep max processes reasonable for CI -commands = pytest {posargs} tests -n auto --maxprocesses=10 --durations=10 --dist=worksteal +commands = + printf '\n\033[1m leanSpec has migrated from tox to just.\033[0m\n\n Use:\n \033[1mjust test\033[0m\n\n' + false [testenv:pytest-cov] -description = Run tests with coverage (pytest) -commands = pytest --cov --cov-report=html --cov-report=term {posargs} +commands = + printf '\n\033[1m leanSpec has migrated from tox to just.\033[0m\n\n Use:\n \033[1mjust test-cov\033[0m\n\n' + false [testenv:pytest-cov-gate] -description = Run tests with coverage gate (fails below 80%) -commands = pytest --cov --cov-report=term-missing --cov-fail-under=80 {posargs} +commands = + printf '\n\033[1m leanSpec has migrated from tox to just.\033[0m\n\n Use:\n \033[1mjust test-cov-gate\033[0m\n\n' + false [testenv:pytest-consensus] -description = Run consensus tests (pytest) -commands = pytest {posargs} -n auto --maxprocesses=10 --durations=10 --dist=worksteal \ - tests/lean_spec/subspecs/containers \ - tests/lean_spec/subspecs/forkchoice \ - tests/lean_spec/subspecs/networking +commands = + printf '\n\033[1m leanSpec has migrated from tox to just.\033[0m\n\n Use:\n \033[1mjust test-consensus\033[0m\n\n' + false [testenv:docs-build] -description = Build documentation (mkdocs) -commands = mkdocs build {posargs} +commands = + printf '\n\033[1m leanSpec has migrated from tox to just.\033[0m\n\n Use:\n \033[1mjust docs\033[0m\n\n' + false [testenv:docs-serve] -description = Serve documentation locally (mkdocs) -commands = mkdocs serve {posargs} +commands = + printf '\n\033[1m leanSpec has migrated from tox to just.\033[0m\n\n Use:\n \033[1mjust docs-serve\033[0m\n\n' + false