Justfile

set positional-arguments := true

alias help := default

# List available recipes
default:
    @just --list

# Run all quality checks (lint, format, typecheck, spellcheck, mdformat, lock)
[group('quality')]
check: lint format-check typecheck spellcheck mdformat lock-check

# Lint with ruff (no auto-fix)
[group('quality')]
lint *args:
    uv run --group lint ruff check --no-fix --show-fixes "$@"

# Format code with ruff
[group('quality')]
format *args:
    uv run --group lint ruff format "$@"

# Verify formatting with ruff (no changes)
[group('quality')]
format-check *args:
    uv run --group lint ruff format --check "$@"

# Auto-fix lint, formatting, and markdown issues
[group('quality')]
fix:
    uv run --group lint ruff check --fix
    uv run --group lint ruff format
    uv run --group docs mdformat docs/

# Type check with ty
[group('quality')]
typecheck *args:
    uv run --group lint ty check "$@"

# Detect dead code with vulture (paths and ignores configured in pyproject.toml)
[group('quality')]
deadcode *args:
    uv run --group lint vulture "$@"

# Spell check source, tests, packages, and docs
[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/node/snappy/testdata" --ignore-words=.codespell-ignore-words.txt "$@"

# Verify markdown formatting in docs/
[group('quality')]
mdformat *args:
    uv run --group docs mdformat --check docs/ "$@"

# Verify uv.lock is up to date
[group('quality')]
lock-check:
    #!/usr/bin/env bash
    if ! uv lock --check; then
        echo ""
        echo "uv.lock is out of date. To sync:"
        echo "  uv lock"
        echo ""
        echo "Then commit the updated uv.lock."
        exit 1
    fi

# Run unit tests in parallel
[group('tests')]
test *args:
    uv run --group test pytest tests -n auto --maxprocesses=10 --durations=10 --dist=worksteal "$@"

# Run unit tests with coverage report (HTML + terminal)
[group('tests')]
test-cov *args:
    uv run --group test pytest --cov --cov-report=html --cov-report=term "$@"

# Run unit tests with coverage gate (fails below 80%)
[group('tests')]
test-cov-gate *args:
    uv run --group test pytest --cov --cov-report=term-missing --cov-fail-under=80 "$@"

# Run consensus-only unit tests (containers, forkchoice, networking)
[group('tests')]
test-consensus *args:
    uv run --group test pytest -n auto --maxprocesses=10 --durations=10 --dist=worksteal tests/node/networking "$@"

# Canonical CI fixture run; contributors should use `uv run fill` directly.
# FILL_WORKERS overrides the xdist worker count (defaults to one per core).
# The prod scheme lowers it so real proofs are not starved of rayon threads.
[group('tests'), private]
fill-ci *args:
    uv run --group test fill --fork=Lstar --clean -n "${FILL_WORKERS:-auto}" --dist=worksteal "$@"

# Standalone determinism audit: regenerate vectors twice under different hash seeds and diff.
# Every fill run already does this over the whole consensus tree as its per-fill gate.
# That gate covers all emitted vectors, with no opt-in marker or subset.
# This recipe runs the same audit on its own, scoped to whatever target it is given.
# Pass a path to point the audit at part of the tree (for example a single filler).
# A difference means an emitted vector depends on set or dict iteration order,
# which is hash-seeded and would break cross-client reproducibility.
[group('tests')]
fill-determinism *args:
    #!/usr/bin/env bash
    set -euo pipefail
    target="{{args}}"
    [ -z "$target" ] && target="tests/consensus"
    first="$(mktemp -d)"
    second="$(mktemp -d)"
    trap 'rm -rf "$first" "$second"' EXIT
    # Single process: one process pins the hash seed cleanly, which is what the
    # audit needs, so the xdist worker fan-out is intentionally skipped here.
    # This recipe is itself the determinism check, so the per-fill gate is skipped.
    PYTHONHASHSEED=1 uv run --group test fill --fork=Lstar --clean --no-check-determinism -n 0 -o "$first" $target -q
    PYTHONHASHSEED=2 uv run --group test fill --fork=Lstar --clean --no-check-determinism -n 0 -o "$second" $target -q
    if diff -rq "$first" "$second"; then
        echo "Determinism check passed: fixtures are byte-identical across hash seeds."
    else
        echo "Determinism check FAILED: emitted vectors differ across PYTHONHASHSEED." >&2
        exit 1
    fi

# Run API conformance tests against an external client
[group('tests')]
apitest server_url *args:
    uv run --group test apitest "{{server_url}}" "$@"

# Run multi-node interop tests
[group('tests')]
interop *args:
    uv run --group test pytest tests/interop/ -v --no-cov --timeout=120 -x --tb=short --log-cli-level=INFO "$@"

# Build documentation site with mkdocs
[group('docs')]
docs *args:
    uv run --group docs mkdocs build "$@"

# Serve documentation locally with mkdocs (live reload)
[group('docs')]
docs-serve *args:
    uv run --group docs mkdocs serve "$@"

# Print the command to install shell completions for just recipes
[group('housekeeping')]
shell-completions:
    #!/usr/bin/env bash
    case "$(basename "$SHELL")" in
        bash)
            echo "Run the following commands to install just completions for bash:"
            echo ""
            echo "  mkdir -p ~/.local/share/bash-completion/completions"
            echo "  just --completions bash > ~/.local/share/bash-completion/completions/just"
            ;;
        zsh)
            echo "Run the following commands to install just completions for zsh:"
            echo ""
            echo "  mkdir -p ~/.zsh/completions"
            echo "  just --completions zsh > ~/.zsh/completions/_just"
            echo ""
            echo "Then add to your .zshrc:"
            echo ""
            echo "  fpath=(~/.zsh/completions \$fpath)"
            echo "  autoload -U compinit"
            echo "  compinit"
            ;;
        fish)
            echo "Run the following commands to install just completions for fish:"
            echo ""
            echo "  mkdir -p ~/.config/fish/completions"
            echo "  just --completions fish > ~/.config/fish/completions/just.fish"
            ;;
        *)
            echo "See the link below for instructions for your shell."
            ;;
    esac
    echo ""
    echo "For more details, see https://just.systems/man/en/shell-completion-scripts.html"