build-and-test.yml

name: Build and Test Workflow

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]
  schedule:
    # midnight EST
    - cron:  '0 5 * * *'
  # allow this to be scheduled manually in addition to cron
  workflow_dispatch:

permissions:
  contents: read

jobs:
  tests:
    # Default matrix: bare-import balance on every OS / python combination —
    # the regression guard against accidentally hard-depending on diff-diff.
    # `extras='did'` permutations are layered in via the `include:` block
    # below so the `diff-diff-pin` axis only multiplies jobs for the `did`
    # arm (avoids the earlier mistake where two `extras: ''` excludes
    # silently removed every bare-import job).
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        python-version: ['3.9', '3.10', '3.11', '3.12', '3.13', '3.14']
        extras: ['']
        diff-diff-pin: ['']
        include:
          # diff-diff [did] integration coverage. Restricted to ubuntu-latest
          # AND a single Python version (3.12) to keep the matrix small (2
          # jobs total: one min-pin, one resolved-latest). diff-diff is a
          # pure-Python adapter dependency, so multi-Python coverage adds
          # very little signal -- the bare-import balance matrix above
          # already exercises 3.9 - 3.14 across all three OSes. The weekly
          # canary in diff-diff-canary.yml additionally tests against the
          # absolute latest PyPI release (no pin) on 3.12. If you need
          # macOS/Windows or other-Python coverage of the [did] arm, add
          # explicit matrix entries here rather than relying on the canary.
          - os: ubuntu-latest
            python-version: '3.12'
            extras: 'did'
            diff-diff-pin: '==3.3.0'
          - os: ubuntu-latest
            python-version: '3.12'
            extras: 'did'
            diff-diff-pin: 'resolved-latest'
      fail-fast: false
    steps:
      - name: Checkout
        uses: actions/checkout@v5
      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}
      - name: Install Pkg + Dependencies
        run: |
          if [ -z "${{ matrix.extras }}" ]; then
            python -m pip install -e ".[dev]"
          else
            python -m pip install -e ".[dev,${{ matrix.extras }}]"
          fi
        shell: bash
      - name: Verify bare `import balance` works (no diff-diff)
        if: matrix.extras == ''
        run: |
          python -c "import balance; print('balance', balance.__version__)"
        shell: bash
      - name: Pin diff-diff to exact minimum (==3.3.0)
        # NOTE: bracket notation `matrix['diff-diff-pin']` is required because
        # GitHub Actions parses `-` in expressions as the subtraction operator,
        # so `matrix.diff-diff-pin` would be evaluated as
        # `matrix.diff - diff - pin` (arithmetic on undefined identifiers) and
        # would never match the literal `'==3.3.0'`, silently skipping this
        # step for every `did` matrix job.
        if: matrix.extras == 'did' && matrix['diff-diff-pin'] == '==3.3.0'
        run: |
          python -m pip install "diff-diff==3.3.0"
      - name: Show installed diff-diff (debugging aid)
        if: matrix.extras == 'did'
        run: |
          python -c "import diff_diff; print('diff_diff', diff_diff.__version__)"
      - name: Test with pytest
        run: |
          python -m pytest -ra
      - name: Build wheels pkg
        run: |
          python -m pip install --upgrade pip build
          python -m build --wheel --outdir dist

  lint:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout
      uses: actions/checkout@v5
    - name: Set up Python
      uses: actions/setup-python@v5
      with:
        python-version: 3.12
    - name: Install dependencies
      run: |
        pip install flake8 black==25.1.0 ufmt==2.8.0 usort==1.0.8.post1
    - name: Flake8
      run: |
        flake8 .
    - name: ufmt (formatting check)
      run: |
        echo "Checking for formatting issues..."
        ufmt diff .
        ufmt check .

  pyre:
    # NOTE: .pyre_configuration.external has "ignore_all_errors" for tests/ - this is intentional.
    # Meta's internal Pyre uses python/typeshed_internal with permissive pandas stubs
    # (Axes = ... | list | tuple), but external pyre-check-nightly uses stricter typeshed
    # stubs that reject tuple/list for DataFrame index/columns. This causes ~85 false-positive
    # errors in tests that don't occur internally. The main library code (balance/) is still
    # fully type-checked.
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v5
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - name: Install project dependencies
        run: |
          python -m pip install --upgrade pip
          pip install .[dev]
      - name: Install Pyre nightly
        run: |
          pip install pyre-check-nightly==0.0.101750936314
      - name: Pyre type check
        run: |
          cp .pyre_configuration.external .pyre_configuration
          pyre --noninteractive check

  test-deploy-website:
    name: Test website build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-node@v5
        with:
          node-version: 22
          cache: yarn
          cache-dependency-path: "./website/yarn.lock"
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          # 3.12 matches the brfss tutorial kernel, the canary, the [did]
          # arm in the test matrix, and the notebook-CI workflow. Earlier
          # versions used 3.9 — diff-diff supports 3.9-3.14 so [did] would
          # still install, but consolidating on 3.12 keeps the docs-build
          # interpreter aligned with the version that actually runs the
          # tutorial in CI.
          python-version: "3.12"
      - name: Install Pkg + Dependencies
        run: |
          python -m pip install ".[dev,did]"
      - name: Build website
        run: bash ./scripts/make_docs.sh -n