ci-cd.yml

name: CI/CD Pipeline

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]
  workflow_dispatch:
    inputs:
      changelog_summary:
        description: "Plain-English summary for CHANGELOG (optional)."
        required: false
        default: ""

permissions:
  contents: write

jobs:
  test:
    name: Test & Lint (${{ matrix.os }} / py${{ matrix.python-version }})
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
        python-version: ["3.9", "3.10", "3.11", "3.12"]

    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0 # Fetch all history for changelog/commit analysis if needed

      - name: Install uv
        uses: astral-sh/setup-uv@v3
        with:
          enable-cache: true
          cache-dependency-glob: "uv.lock"

      - name: Install dependencies
        run: uv sync --all-extras --dev

      - name: Lint with Ruff
        run: uv run ruff check .

      - name: Test with pytest (and coverage)
        run: uv run pytest -v --cov=src --cov-report=xml

      - name: Upload coverage to Codecov
        uses: codecov/codecov-action@v4
        with:
          token: ${{ secrets.CODECOV_TOKEN }}
          file: ./coverage.xml
          fail_ci_if_error: false # Don't fail the build if codecov is just down/unconfigured

      - name: Prune uv cache
        run: uv cache prune --ci

  docs:
    name: Build Documentation
    runs-on: ubuntu-latest
    needs: test # Only build docs if tests pass
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Install uv
        uses: astral-sh/setup-uv@v3

      - name: Install dependencies
        run: uv sync --all-extras --dev

      - name: Build MkDocs
        run: uv run mkdocs build

      # Optional: Deploy to GitHub Pages (disabled for this example, but ready to enable)
      # - name: Deploy to GitHub Pages
      #   uses: mkdocs/gh-deployer@...

  changelog:
    name: Generate Changelog
    runs-on: ubuntu-latest
    if: github.event_name == 'push' && github.ref == 'refs/heads/main' || github.event_name == 'workflow_dispatch'
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0 # Fetch all history for the log

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.10"

      - name: Generate Changelog Entry
        # We run the script directly.
        # It appends to CHANGELOG.md in the runner.
        env:
          CHANGELOG_SUMMARY: ${{ inputs.changelog_summary }}
        run: |
          if [ -n "${CHANGELOG_SUMMARY}" ]; then
            python3 scripts/generate_changelog.py --use-last-tag --summary "${CHANGELOG_SUMMARY}"
          else
            python3 scripts/generate_changelog.py --use-last-tag
          fi

      - name: Commit and Push Changelog
        run: |
          git config --global user.name "github-actions[bot]"
          git config --global user.email "github-actions[bot]@users.noreply.github.com"
          git add CHANGELOG.md
          # Only commit if there are changes
          if git diff --staged --quiet; then
            echo "No changes to commit."
          else
            git commit -m "docs: update changelog [skip ci]"
            git push
          fi

      - name: Upload Changelog Artifact
        uses: actions/upload-artifact@v4
        with:
          name: changelog-update
          path: CHANGELOG.md