ci.yml

# .github/workflows/ci.yml
name: CI - Tests and Documentation

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

permissions:
  contents: read

jobs:
  # Detect which files have changed to conditionally run jobs
  changes:
    name: "Detect Changes"
    runs-on: ubuntu-latest
    outputs:
      agentex: ${{ steps.filter.outputs.agentex }}
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      
      - name: Check for agentex changes
        uses: dorny/paths-filter@v3
        id: filter
        with:
          filters: |
            agentex:
              - 'agentex/**'

  test:
    name: "Run Unit and Integration Tests"
    runs-on: ubuntu-latest
    needs: changes
    if: needs.changes.outputs.agentex == 'true'

    steps:
    # Checkout the repository
    - name: Checkout
      uses: actions/checkout@v4

    # Set up Python and uv
    - name: Set up Python
      uses: actions/setup-python@v5
      with:
        python-version: '3.12'

    - name: Install uv
      uses: astral-sh/setup-uv@v4
      with:
        version: "0.7.3"
        enable-cache: true

    # Cache uv dependencies
    - name: Cache uv dependencies
      uses: actions/cache@v4
      with:
        path: ~/.cache/uv
        key: ${{ runner.os }}-uv-${{ hashFiles('**/agentex/uv.lock', '**/agentex/pyproject.toml') }}
        restore-keys: |
          ${{ runner.os }}-uv-

    # Docker is needed for testcontainers
    - name: Verify Docker is running
      run: |
        docker --version
        docker info

    # Install dependencies
    - name: Install test dependencies
      working-directory: ./agentex
      run: |
        echo "📦 Installing test dependencies (pytest, testcontainers, etc.)..."
        uv sync --group test

    # Run Docker environment setup
    - name: Setup and validate Docker environment for tests
      working-directory: ./agentex
      run: |
        echo "🐳 Setting up Docker environment for testcontainers..."
        uv run python scripts/test_setup.py --check-docker
        echo "✅ Docker environment validated successfully"

    # Run unit tests
    - name: Run unit tests
      working-directory: ./agentex
      timeout-minutes: 10
      run: |
        echo "🧪 Running unit tests..."
        uv run python scripts/run_tests.py -m unit --cov=src --cov-report=xml --cov-report=term

    # Run integration tests (appends to unit coverage)
    - name: Run integration tests
      working-directory: ./agentex
      timeout-minutes: 20
      run: |
        echo "🧪 Running integration tests..."
        uv run python scripts/run_tests.py -m integration --cov=src --cov-report=xml --cov-report=term --pytest-args="--cov-append"

    # Clean up test containers
    - name: Clean up test containers
      if: always()
      run: |
        echo "🧹 Cleaning up any remaining test containers..."
        docker container prune -f || true
        docker volume prune -f || true

    # Upload coverage reports
    - name: Upload coverage to Codecov
      if: always()
      uses: codecov/codecov-action@v4
      with:
        file: ./agentex/coverage.xml
        flags: unittests
        name: agentex-public-coverage
        fail_ci_if_error: false

    # Test summary
    - name: Test Summary
      if: always()
      run: |
        echo "📊 Unit and integration test execution completed"

  docs:
    name: "Build Documentation"
    runs-on: ubuntu-latest
    needs: changes
    if: needs.changes.outputs.agentex == 'true'

    steps:
    # Checkout the repository
    - name: Checkout
      uses: actions/checkout@v4

    # Set up Python and uv
    - name: Set up Python
      uses: actions/setup-python@v5
      with:
        python-version: '3.12'

    - name: Install uv
      uses: astral-sh/setup-uv@v4
      with:
        version: "0.7.3"

    # Build documentation
    - name: Build documentation
      working-directory: ./agentex
      run: |
        echo "📚 Building documentation..."
        # Install docs dependencies
        uv sync --group docs
        # Build documentation
        cd docs && uv run mkdocs build
        echo "✅ Documentation built successfully"

    # Verify docs were built
    - name: Verify documentation
      working-directory: ./agentex
      run: |
        if [ -d "docs/site" ]; then
          echo "✅ Documentation site directory exists"
          ls -la docs/site
        else
          echo "❌ Documentation site directory not found"
          exit 1
        fi

  openapi-spec:
    name: "Verify OpenAPI spec is up to date"
    runs-on: ubuntu-latest
    needs: changes
    if: needs.changes.outputs.agentex == 'true'
    timeout-minutes: 10

    steps:
    - name: Checkout
      uses: actions/checkout@v4

    - name: Set up Python
      uses: actions/setup-python@v5
      with:
        python-version: '3.12'

    - name: Install uv
      uses: astral-sh/setup-uv@v4
      with:
        version: "0.7.3"
        enable-cache: true

    - name: Install dependencies
      working-directory: ./agentex
      run: uv sync

    - name: Regenerate OpenAPI spec
      working-directory: ./agentex
      run: uv run python scripts/generate_openapi_spec.py --output openapi.yaml

    - name: Verify committed spec matches generated spec
      working-directory: ./agentex
      run: |
        if ! git diff --exit-code openapi.yaml; then
          echo "❌ The committed openapi.yaml is out of date."
          echo "Run 'uv run python scripts/generate_openapi_spec.py --output openapi.yaml' from agentex/ and commit the result."
          exit 1
        fi
        echo "✅ openapi.yaml is up to date"

  # This job is used as a required status check for branch protection
  # It will pass if the conditional jobs either passed or were skipped
  ci-status:
    name: "CI Status Check"
    runs-on: ubuntu-latest
    needs: [changes, test, docs, openapi-spec]
    if: always()
    steps:
      - name: Check CI status
        run: |
          # Check if agentex changes were detected
          if [ "${{ needs.changes.outputs.agentex }}" == "true" ]; then
            echo "Agentex changes detected - checking test and docs results"
            
            # Both test and docs must succeed
            if [ "${{ needs.test.result }}" != "success" ]; then
              echo "❌ Tests failed"
              exit 1
            fi
            
            if [ "${{ needs.docs.result }}" != "success" ]; then
              echo "❌ Documentation build failed"
              exit 1
            fi

            if [ "${{ needs.openapi-spec.result }}" != "success" ]; then
              echo "❌ OpenAPI spec freshness check failed"
              exit 1
            fi

            echo "✅ All checks passed"
          else
            echo "No agentex changes detected - skipping tests and docs"
            echo "✅ CI status check passed"
          fi