python.yml

name: Python CI/CD Pipeline

on:
  push:
    branches:
      - main
    paths:
      - 'python/**'
      - '.github/workflows/python.yml'
  pull_request:
    types: [opened, synchronize, reopened]
    paths:
      - 'python/**'
      - '.github/workflows/python.yml'
  workflow_dispatch:
    inputs:
      bump_type:
        description: 'Version bump type'
        required: true
        type: choice
        options:
          - patch
          - minor
          - major
      description:
        description: 'Release description (optional)'
        required: false
        type: string

defaults:
  run:
    working-directory: python

env:
  GIT_CONFIG_COUNT: '1'
  GIT_CONFIG_KEY_0: init.defaultBranch
  GIT_CONFIG_VALUE_0: main

jobs:
  # === DETECT CHANGES - determines which jobs should run ===
  detect-changes:
    name: Detect Changes
    runs-on: ubuntu-latest
    timeout-minutes: 5
    concurrency:
      group: ${{ github.workflow }}-${{ github.ref }}-detect-changes
      cancel-in-progress: true
    if: github.event_name != 'workflow_dispatch'
    outputs:
      py-changed: ${{ steps.changes.outputs.py-changed }}
      tests-changed: ${{ steps.changes.outputs.tests-changed }}
      package-changed: ${{ steps.changes.outputs.package-changed }}
      docs-changed: ${{ steps.changes.outputs.docs-changed }}
      workflow-changed: ${{ steps.changes.outputs.workflow-changed }}
      any-code-changed: ${{ steps.changes.outputs.any-code-changed }}
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0

      - name: Setup Python
        uses: actions/setup-python@v6
        with:
          python-version: '3.13'

      - name: Detect changes
        id: changes
        env:
          GITHUB_EVENT_NAME: ${{ github.event_name }}
          GITHUB_BASE_SHA: ${{ github.event.pull_request.base.sha }}
          GITHUB_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
        run: python scripts/detect_code_changes.py

  # === CHANGELOG CHECK - only runs on PRs with code changes ===
  # Docs-only PRs (./docs folder, markdown files) don't require changelog fragments
  changelog:
    name: Changelog Fragment Check
    runs-on: ubuntu-latest
    timeout-minutes: 10
    concurrency:
      group: ${{ github.workflow }}-${{ github.ref }}-changelog
      cancel-in-progress: true
    needs: [detect-changes]
    if: github.event_name == 'pull_request' && needs.detect-changes.outputs.any-code-changed == 'true'
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0

      - name: Set up Python
        uses: actions/setup-python@v6
        with:
          python-version: "3.13"

      - name: Install scriv
        run: pip install "scriv[toml]"

      - name: Check for changelog fragments
        # GITHUB_BASE_REF is passed as an environment variable rather than
        # interpolated into the script body: a branch name is attacker-controlled
        # data on pull_request events.
        env:
          GITHUB_BASE_REF: ${{ github.base_ref }}
        run: |
          set -euo pipefail

          # Get list of fragment files (excluding README and template)
          FRAGMENTS=$(find changelog.d -name "*.md" ! -name "README.md" ! -name "*.j2" 2>/dev/null | wc -l)

          # Get changed files in PR
          CHANGED_FILES=$(git diff --name-only "origin/${GITHUB_BASE_REF}...HEAD")

          # Check if any source files changed (excluding docs and config)
          SOURCE_CHANGED=$(printf '%s\n' "$CHANGED_FILES" | grep -cE "^python/(src/|tests/|scripts/)" || true)

          if [ "$SOURCE_CHANGED" -gt 0 ] && [ "$FRAGMENTS" -eq 0 ]; then
            echo "::error::No changelog fragment found. Please run 'scriv create' and document your changes."
            echo ""
            echo "To create a changelog fragment:"
            echo "  pip install 'scriv[toml]'"
            echo "  scriv create"
            echo ""
            echo "This is similar to adding a changeset in JavaScript projects."
            echo "See changelog.d/README.md for more information."
            exit 1
          fi

          echo "Changelog check passed"

  # === LINT AND FORMAT CHECK ===
  lint:
    name: Lint and Format Check
    runs-on: ubuntu-latest
    timeout-minutes: 10
    concurrency:
      group: ${{ github.workflow }}-${{ github.ref }}-lint
      cancel-in-progress: true
    needs: [detect-changes]
    # !cancelled() is required because detect-changes is skipped on
    # workflow_dispatch. Without it, a skipped dependency skips this job too,
    # which in turn skipped manual-release (it needs lint), making the manual
    # release path unreachable.
    # See: https://github.com/actions/runner/issues/491
    if: |
      !cancelled() && (
        github.event_name == 'push' ||
        github.event_name == 'workflow_dispatch' ||
        needs.detect-changes.outputs.py-changed == 'true' ||
        needs.detect-changes.outputs.tests-changed == 'true' ||
        needs.detect-changes.outputs.docs-changed == 'true' ||
        needs.detect-changes.outputs.package-changed == 'true' ||
        needs.detect-changes.outputs.workflow-changed == 'true'
      )
    steps:
      - uses: actions/checkout@v6
        with:
          # Full history: simulate-fresh-merge.sh needs a merge base.
          fetch-depth: 0

      # Lint the state that will exist after the merge, not the stale merge
      # preview GitHub built when the pull request was last synced.
      - name: Simulate fresh merge with base branch (PR only)
        if: github.event_name == 'pull_request'
        env:
          BASE_REF: ${{ github.base_ref }}
        # The job default working-directory is the language subdirectory, and
        # the shared script lives at the repository root. shell: bash is
        # explicit because the Windows runners default to pwsh.
        working-directory: .
        shell: bash
        run: bash scripts/simulate-fresh-merge.sh

      - name: Setup Python
        uses: actions/setup-python@v6
        with:
          python-version: '3.13'

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -e ".[dev]"

      - name: Run Ruff linting
        run: ruff check .

      - name: Check Ruff formatting
        run: ruff format --check .

      - name: Run mypy
        run: mypy src

      - name: Check file size limit
        run: python scripts/check_file_size.py

  # === TEST ===
  test:
    name: Test (Python ${{ matrix.python-version }} on ${{ matrix.os }})
    runs-on: ${{ matrix.os }}
    timeout-minutes: 20
    concurrency:
      group: ${{ github.workflow }}-${{ github.ref }}-test-${{ matrix.python-version }}-${{ matrix.os }}
      cancel-in-progress: true
    needs: [detect-changes, changelog]
    # Run if: push event, OR changelog succeeded, OR changelog was skipped (docs-only PR)
    if: >-
      !cancelled() && (github.event_name == 'push' || github.event_name == 'workflow_dispatch' || needs.changelog.result == 'success' || needs.changelog.result == 'skipped')
    env:
      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        python-version: ['3.13']
    steps:
      - uses: actions/checkout@v6
        with:
          # Full history: simulate-fresh-merge.sh needs a merge base.
          fetch-depth: 0

      # Test the state that will exist after the merge. This is the check that
      # catches a semantic conflict: two pull requests that each pass alone but
      # break the suite once both are on the base branch.
      - name: Simulate fresh merge with base branch (PR only)
        if: github.event_name == 'pull_request'
        env:
          BASE_REF: ${{ github.base_ref }}
        # The job default working-directory is the language subdirectory, and
        # the shared script lives at the repository root. shell: bash is
        # explicit because the Windows runners default to pwsh.
        working-directory: .
        shell: bash
        run: bash scripts/simulate-fresh-merge.sh

      - name: Setup Python
        uses: actions/setup-python@v6
        with:
          python-version: ${{ matrix.python-version }}

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -e ".[dev]"

      - name: Run tests
        run: pytest tests/ -v --cov=src --cov-report=xml --cov-report=term

      # Gate on the token rather than uploading unconditionally: without it the
      # action fails on forks, which have no secrets. With the token present an
      # upload error is a real failure, so fail_ci_if_error is true. It was
      # false, which meant a genuinely failed upload still reported success --
      # the coverage report silently stopped updating and nothing said so.
      - name: Upload coverage to Codecov
        if: >-
          matrix.os == 'ubuntu-latest' && matrix.python-version == '3.13' &&
          env.CODECOV_TOKEN != ''
        uses: codecov/codecov-action@v7
        with:
          token: ${{ env.CODECOV_TOKEN }}
          files: ./python/coverage.xml
          disable_search: true
          fail_ci_if_error: true
          flags: python

      - name: Report skipped Codecov upload
        if: >-
          matrix.os == 'ubuntu-latest' && matrix.python-version == '3.13' &&
          env.CODECOV_TOKEN == ''
        run: echo "::notice::Skipping Codecov upload because CODECOV_TOKEN is not configured"

  # === BUILD PACKAGE ===
  build:
    name: Build Package
    runs-on: ubuntu-latest
    timeout-minutes: 10
    concurrency:
      group: ${{ github.workflow }}-${{ github.ref }}-build
      cancel-in-progress: true
    needs: [detect-changes, lint, test]
    # Build only after the quality gates pass. 'skipped' is accepted because a
    # docs-only pull request legitimately skips lint/test; 'failure' never is.
    # The previous condition short-circuited on `github.event_name == 'push'`,
    # so a failing lint on main still produced a build artifact.
    if: |
      !cancelled() &&
      (needs.lint.result == 'success' || needs.lint.result == 'skipped') &&
      (needs.test.result == 'success' || needs.test.result == 'skipped')
    steps:
      - uses: actions/checkout@v6

      - name: Setup Python
        uses: actions/setup-python@v6
        with:
          python-version: '3.13'

      - name: Install build dependencies
        run: |
          python -m pip install --upgrade pip
          pip install build twine

      - name: Build package
        run: python -m build

      - name: Check package
        run: twine check dist/*

      - name: Upload artifacts
        uses: actions/upload-artifact@v7
        with:
          name: python-dist
          path: python/dist/

  # === AUTO RELEASE - triggers on push to main if version changed ===
  auto-release:
    name: Auto Release
    needs: [lint, test, build]
    timeout-minutes: 30
    concurrency:
      group: main-writer-${{ github.repository }}-main
      cancel-in-progress: false
    # !cancelled() plus explicit success checks: a cancelled or failed gate must
    # never publish, and a gate that was skipped for an unrelated reason must
    # not be treated as a pass.
    if: |
      !cancelled() &&
      github.event_name == 'push' &&
      github.ref == 'refs/heads/main' &&
      needs.lint.result == 'success' &&
      needs.test.result == 'success' &&
      needs.build.result == 'success'
    runs-on: ubuntu-latest
    permissions:
      contents: write
      id-token: write
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0

      - name: Setup Python
        uses: actions/setup-python@v6
        with:
          python-version: '3.13'

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install build twine

      - name: Check if version changed
        id: version_check
        run: |
          # Get current version from pyproject.toml
          CURRENT_VERSION=$(grep -Po '(?<=^version = ")[^"]*' pyproject.toml)
          echo "current_version=$CURRENT_VERSION" >> $GITHUB_OUTPUT

          # Check if tag exists (with python prefix to differentiate from JS/Rust)
          if git rev-parse "python-v$CURRENT_VERSION" >/dev/null 2>&1; then
            echo "Tag python-v$CURRENT_VERSION already exists, skipping release"
            echo "should_release=false" >> $GITHUB_OUTPUT
          else
            echo "New version detected: $CURRENT_VERSION"
            echo "should_release=true" >> $GITHUB_OUTPUT
          fi

      - name: Download artifacts
        if: steps.version_check.outputs.should_release == 'true'
        uses: actions/download-artifact@v7
        with:
          name: python-dist
          path: python/dist/

      - name: Publish to PyPI
        if: steps.version_check.outputs.should_release == 'true'
        uses: pypa/gh-action-pypi-publish@release/v1
        with:
          packages-dir: python/dist/

      - name: Create GitHub Release
        if: steps.version_check.outputs.should_release == 'true'
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          python scripts/create_github_release.py \
            --version "${{ steps.version_check.outputs.current_version }}" \
            --repository "${{ github.repository }}" \
            --tag-prefix "python-v"

  # === MANUAL RELEASE - triggered via workflow_dispatch ===
  manual-release:
    name: Manual Release
    needs: [lint, test, build]
    timeout-minutes: 30
    concurrency:
      group: main-writer-${{ github.repository }}-main
      cancel-in-progress: false
    # Previously this job could never run: detect-changes is skipped on
    # workflow_dispatch, which skipped lint, which skipped this job because a
    # skipped dependency skips dependents unless the condition survives it.
    if: |
      !cancelled() &&
      github.event_name == 'workflow_dispatch' &&
      needs.lint.result == 'success' &&
      needs.test.result == 'success' &&
      needs.build.result == 'success'
    runs-on: ubuntu-latest
    permissions:
      contents: write
      id-token: write
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0
          token: ${{ secrets.GITHUB_TOKEN }}

      - name: Setup Python
        uses: actions/setup-python@v6
        with:
          python-version: '3.13'

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install build twine "scriv[toml]"

      - name: Configure git
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"

      - name: Collect changelog fragments
        run: |
          # Check if there are any fragments to collect
          FRAGMENTS=$(find changelog.d -name "*.md" ! -name "README.md" ! -name "*.j2" 2>/dev/null | wc -l)
          if [ "$FRAGMENTS" -gt 0 ]; then
            echo "Found $FRAGMENTS changelog fragment(s), collecting..."
            scriv collect --version "${{ github.event.inputs.bump_type }}"
          else
            echo "No changelog fragments found, skipping collection"
          fi

      - name: Version and commit
        id: version
        # RELEASE_DESCRIPTION is a free-form workflow_dispatch input, so it is
        # passed through the environment instead of being interpolated into the
        # shell command.
        env:
          RELEASE_DESCRIPTION: ${{ github.event.inputs.description }}
        run: |
          python scripts/version_and_commit.py \
            --bump-type "${{ github.event.inputs.bump_type }}" \
            --description "$RELEASE_DESCRIPTION"

      - name: Build package
        if: steps.version.outputs.version_committed == 'true' || steps.version.outputs.already_released == 'true'
        run: python -m build

      - name: Check package
        if: steps.version.outputs.version_committed == 'true' || steps.version.outputs.already_released == 'true'
        run: twine check dist/*

      - name: Publish to PyPI
        if: steps.version.outputs.version_committed == 'true' || steps.version.outputs.already_released == 'true'
        uses: pypa/gh-action-pypi-publish@release/v1
        with:
          packages-dir: python/dist/

      - name: Create GitHub Release
        if: steps.version.outputs.version_committed == 'true' || steps.version.outputs.already_released == 'true'
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          python scripts/create_github_release.py \
            --version "${{ steps.version.outputs.new_version }}" \
            --repository "${{ github.repository }}" \
            --tag-prefix "python-v"