ci.yml

name: CI/CD Pipeline

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main, develop]
  release:
    types: [published]

# Global permissions for the entire workflow
permissions:
  contents: read
  issues: write
  checks: write
  pull-requests: write
  actions: read

env:
  CONAN_USER_HOME: "${{ github.workspace }}/conan-cache"

jobs:
  # ============================================================================
  # YAML Validation
  # ============================================================================

  yaml-validation:
    name: "YAML Validation"
    runs-on: ubuntu-latest
    if: contains(github.event.head_commit.modified, '.yml') || contains(github.event.head_commit.added, '.yml') || contains(github.event.head_commit.modified, '.yaml') || contains(github.event.head_commit.added, '.yaml')

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

      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: "3.11"

      - name: Install YAML validation tools
        run: |
          pip install pyyaml yamllint

      - name: Find changed YAML files
        id: changed-files
        run: |
          # Get list of changed YAML files
          if [ "${{ github.event_name }}" = "pull_request" ]; then
            # For PRs, compare with base branch
            git fetch origin ${{ github.base_ref }}
            CHANGED_FILES=$(git diff --name-only origin/${{ github.base_ref }}...HEAD | grep -E '\.(yml|yaml)$' || true)
          else
            # For pushes, use the commit range
            CHANGED_FILES=$(git diff --name-only ${{ github.event.before }}..${{ github.sha }} | grep -E '\.(yml|yaml)$' || true)
          fi

          echo "changed_files<<EOF" >> $GITHUB_OUTPUT
          echo "$CHANGED_FILES" >> $GITHUB_OUTPUT
          echo "EOF" >> $GITHUB_OUTPUT

          if [ -n "$CHANGED_FILES" ]; then
            echo "Found changed YAML files:"
            echo "$CHANGED_FILES"
          else
            echo "No YAML files changed"
          fi

      - name: Validate YAML syntax
        if: steps.changed-files.outputs.changed_files != ''
        run: |
          echo "Validating YAML syntax for changed files..."
          echo "${{ steps.changed-files.outputs.changed_files }}" | while IFS= read -r file; do
            if [ -n "$file" ] && [ -f "$file" ]; then
              echo "🔍 Validating: $file"
              # Basic Python YAML syntax check
              python -c "import yaml; yaml.safe_load(open('$file', 'r'))" || {
                echo "❌ YAML syntax error in: $file"
                exit 1
              }
              echo "✅ Valid YAML syntax: $file"
            fi
          done

      - name: Lint YAML files with yamllint
        if: steps.changed-files.outputs.changed_files != ''
        run: |
          echo "Running yamllint on changed files..."
          # Create yamllint config for GitHub Actions workflows
          cat > .yamllint.yml << 'EOF'
          extends: default
          rules:
            line-length:
              max: 120
            indentation:
              spaces: 2
            truthy:
              allowed-values: ['true', 'false']
              check-keys: false
            comments:
              min-spaces-from-content: 1
          EOF

          echo "${{ steps.changed-files.outputs.changed_files }}" | while IFS= read -r file; do
            if [ -n "$file" ] && [ -f "$file" ]; then
              echo "🔍 Linting: $file"
              yamllint -c .yamllint.yml "$file" || {
                echo "❌ YAML linting failed for: $file"
                exit 1
              }
              echo "✅ YAML linting passed: $file"
            fi
          done

      - name: Validate GitHub Actions workflow syntax
        if: steps.changed-files.outputs.changed_files != ''
        run: |
          echo "Validating GitHub Actions workflow syntax..."
          echo "${{ steps.changed-files.outputs.changed_files }}" | while IFS= read -r file; do
            if [ -n "$file" ] && [ -f "$file" ] && [[ "$file" == .github/workflows/* ]]; then
              echo "🔍 Validating GitHub Actions workflow: $file"
              # Check for required fields in GitHub Actions workflows
              python << 'PYEOF'
          import yaml
          import sys

          try:
              with open("$file", 'r') as f:
                  workflow = yaml.safe_load(f)
              
              # Check required fields for GitHub Actions workflows
              if 'name' not in workflow:
                  print(f"❌ Missing 'name' field in workflow: $file")
                  sys.exit(1)
              
              if 'on' not in workflow:
                  print(f"❌ Missing 'on' field in workflow: $file")
                  sys.exit(1)
              
              if 'jobs' not in workflow:
                  print(f"❌ Missing 'jobs' field in workflow: $file")
                  sys.exit(1)
              
              # Validate each job has required fields
              for job_name, job_config in workflow['jobs'].items():
                  if not isinstance(job_config, dict):
                      print(f"❌ Job '{job_name}' must be a dictionary in: $file")
                      sys.exit(1)
                  
                  if 'runs-on' not in job_config:
                      print(f"❌ Job '{job_name}' missing 'runs-on' field in: $file")
                      sys.exit(1)
              
              print(f"✅ Valid GitHub Actions workflow: $file")

          except Exception as e:
              print(f"❌ Error validating workflow {file}: {e}")
              sys.exit(1)
          PYEOF
            fi
          done

  # ============================================================================
  # Linux x64 - GCC 13
  # ============================================================================

  linux-gcc:
    name: "Linux GCC 13 (x64)"
    runs-on: ubuntu-24.04
    needs: [yaml-validation]
    if: always() && (needs.yaml-validation.result == 'success' || needs.yaml-validation.result == 'skipped')
    strategy:
      matrix:
        build_type: [Debug, Release]

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

      - name: Install system dependencies
        run: |
          sudo apt update
          sudo apt install -y cmake python3-pip git clang-format
          # Install exact GCC version 13.3.0 to match local development environment
          sudo apt install -y gcc-13 g++-13
          # Set up alternatives to ensure we use GCC 13
          sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-13 100
          sudo update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-13 100

      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: "3.11"

      - name: Install Conan
        run: |
          pip3 install --user conan
          echo "$HOME/.local/bin" >> $GITHUB_PATH

      - name: Setup Conan profile
        run: |
          conan profile detect --force
          # Use static profile for GCC 13 with C++23
          sed -i 's/compiler=.*/compiler=gcc/' ~/.conan2/profiles/default
          sed -i 's/compiler.version=.*/compiler.version=13/' ~/.conan2/profiles/default
          sed -i 's/compiler.libcxx=.*/compiler.libcxx=libstdc++11/' ~/.conan2/profiles/default
          sed -i 's/compiler.cppstd=.*/compiler.cppstd=23/' ~/.conan2/profiles/default
          sed -i 's/os=.*/os=Linux/' ~/.conan2/profiles/default
          sed -i 's/arch=.*/arch=x86_64/' ~/.conan2/profiles/default
          echo "=== Conan Profile ==="
          conan profile show --profile:host=default

      - name: Cache Conan packages
        uses: actions/cache@v4
        with:
          path: ~/.conan2
          key: conan-linux-gcc-${{ matrix.build_type }}-${{ hashFiles('conanfile.py') }}
          restore-keys: |
            conan-linux-gcc-${{ matrix.build_type }}-
            conan-linux-gcc-

      - name: Install dependencies
        run: |
          export CC=gcc
          export CXX=g++
          conan install . -s os=Linux -s build_type=${{ matrix.build_type }} --output-folder=build --build=missing -o with_gperftools=True

      - name: Configure CMake
        run: |
          export CC=gcc
          export CXX=g++
          if [[ "${{ matrix.build_type }}" == "Debug" ]]; then
            cmake --preset conan-debug \
              -DCOMPILER_TYPE=GCC \
              -DUSE_LTO=ON \
              -DUSE_NATIVE_ARCH=ON \
              -DENABLE_SHARED_LIBRARY=ON
          else
            cmake --preset conan-release \
              -DCOMPILER_TYPE=GCC \
              -DUSE_LTO=ON \
              -DUSE_NATIVE_ARCH=ON \
              -DENABLE_SHARED_LIBRARY=ON
          fi

      - name: Build
        run: |
          if [[ "${{ matrix.build_type }}" == "Debug" ]]; then
            cmake --build --preset conan-debug --parallel
          else
            cmake --build --preset conan-release --parallel
          fi

      - name: Test
        run: |
          # Both Debug and Release builds use build/build directory with Conan presets
          cd build/build
          if [[ "${{ matrix.build_type }}" == "Debug" ]]; then
            ./utf_strings-tests --gtest_output=xml:test_results_gcc_debug.xml
          else
            ./utf_strings-tests --gtest_output=xml:test_results_gcc_release.xml
          fi

      - name: Benchmark (Release only)
        if: matrix.build_type == 'Release'
        run: |
          cd build/build
          ./utf_strings-bench --benchmark_min_time=0.1s --benchmark_format=json --benchmark_out=benchmark_results_gcc.json

      - name: Check code formatting (Release only)
        if: matrix.build_type == 'Release'
        run: cmake --build --preset conan-release --target format-check

      - name: Upload test results
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: test-results-linux-gcc-${{ matrix.build_type }}
          path: |
            build/build/test_results_gcc_debug.xml
            build/build/test_results_gcc_release.xml
            build/build/benchmark_results_gcc.json

  # ============================================================================
  # Linux x64 - Clang 18
  # ============================================================================

  linux-clang:
    name: "Linux Clang 18 (x64)"
    runs-on: ubuntu-24.04
    needs: [yaml-validation]
    if: always() && (needs.yaml-validation.result == 'success' || needs.yaml-validation.result == 'skipped')
    strategy:
      matrix:
        build_type: [Debug, Release]

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

      - name: Install system dependencies
        timeout-minutes: 15
        run: |
          set -e  # Exit on any error

          # Update package list first
          sudo apt update

          # Install basic dependencies first (these are fast and reliable)
          sudo apt install -y cmake python3-pip git wget curl

          # Install Clang 18 with timeout and retry logic
          echo "Installing Clang 18..."
          for i in {1..3}; do
            if timeout 10m bash -c "
              wget -q https://apt.llvm.org/llvm.sh &&
              chmod +x llvm.sh &&
              sudo ./llvm.sh 18
            "; then
              echo "LLVM installation successful on attempt $i"
              break
            else
              echo "LLVM installation attempt $i failed, retrying..."
              rm -f llvm.sh
              if [ $i -eq 3 ]; then
                echo "All LLVM installation attempts failed"
                exit 1
              fi
              sleep 30
            fi
          done

          # Install additional tools
          sudo apt install -y clang-format-18 || {
            echo "clang-format-18 not available, trying alternatives..."
            sudo apt install -y clang-format || echo "clang-format installation failed"
          }

          # Set up symlinks
          sudo ln -sf /usr/bin/clang-18 /usr/bin/clang
          sudo ln -sf /usr/bin/clang++-18 /usr/bin/clang++
          if command -v clang-format-18 >/dev/null 2>&1; then
            sudo ln -sf /usr/bin/clang-format-18 /usr/bin/clang-format
          fi

          # Verify installation
          clang --version
          clang++ --version

      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: "3.11"

      - name: Install Conan
        run: |
          pip3 install --user conan
          echo "$HOME/.local/bin" >> $GITHUB_PATH

      - name: Setup Conan profile
        run: |
          conan profile detect --force
          # Use static profile for Clang 18 with C++23
          sed -i 's/compiler=.*/compiler=clang/' ~/.conan2/profiles/default
          sed -i 's/compiler.version=.*/compiler.version=18/' ~/.conan2/profiles/default
          sed -i 's/compiler.libcxx=.*/compiler.libcxx=libstdc++11/' ~/.conan2/profiles/default
          sed -i 's/compiler.cppstd=.*/compiler.cppstd=23/' ~/.conan2/profiles/default
          sed -i 's/os=.*/os=Linux/' ~/.conan2/profiles/default
          sed -i 's/arch=.*/arch=x86_64/' ~/.conan2/profiles/default
          echo "=== Conan Profile ==="
          conan profile show --profile:host=default

      - name: Cache Conan packages
        uses: actions/cache@v4
        with:
          path: ~/.conan2
          key: conan-linux-clang-${{ matrix.build_type }}-${{ hashFiles('conanfile.py') }}
          restore-keys: |
            conan-linux-clang-${{ matrix.build_type }}-
            conan-linux-clang-

      - name: Install dependencies
        run: |
          export CC=clang
          export CXX=clang++
          conan install . -s os=Linux -s build_type=${{ matrix.build_type }} --output-folder=build --build=missing -o with_gperftools=True

      - name: Configure CMake
        run: |
          export CC=clang
          export CXX=clang++
          if [[ "${{ matrix.build_type }}" == "Debug" ]]; then
            cmake --preset conan-debug \
              -DCOMPILER_TYPE=CLANG \
              -DUSE_LTO=ON \
              -DUSE_NATIVE_ARCH=ON \
              -DUSE_LIBC_PLUS_PLUS=OFF \
              -DENABLE_SHARED_LIBRARY=ON
          else
            cmake --preset conan-release \
              -DCOMPILER_TYPE=CLANG \
              -DUSE_LTO=ON \
              -DUSE_NATIVE_ARCH=ON \
              -DUSE_LIBC_PLUS_PLUS=OFF \
              -DENABLE_SHARED_LIBRARY=ON
          fi

      - name: Build
        run: |
          if [[ "${{ matrix.build_type }}" == "Debug" ]]; then
            cmake --build --preset conan-debug --parallel
          else
            cmake --build --preset conan-release --parallel
          fi

      - name: Test
        run: |
          # Both Debug and Release builds use build/build directory with Conan presets
          cd build/build
          if [[ "${{ matrix.build_type }}" == "Debug" ]]; then
            ./utf_strings-tests --gtest_output=xml:test_results_clang_debug.xml
          else
            ./utf_strings-tests --gtest_output=xml:test_results_clang_release.xml
          fi

      - name: Benchmark (Release only)
        if: matrix.build_type == 'Release'
        run: |
          cd build/build
          ./utf_strings-bench --benchmark_min_time=0.1s --benchmark_format=json --benchmark_out=benchmark_results_clang.json

      - name: Check code formatting (Release only)
        if: matrix.build_type == 'Release'
        run: cmake --build --preset conan-release --target format-check

      - name: Upload test results
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: test-results-linux-clang-${{ matrix.build_type }}
          path: |
            build/build/test_results_clang_debug.xml
            build/build/test_results_clang_release.xml
            build/build/benchmark_results_clang.json

  # ============================================================================
  # Linux x64 - Clang Debug with Code Coverage
  # ============================================================================

  linux-clang-coverage:
    name: "Linux Clang Code Coverage (x64)"
    runs-on: ubuntu-24.04
    needs: [yaml-validation]
    if: always() && (needs.yaml-validation.result == 'success' || needs.yaml-validation.result == 'skipped')

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

      - name: Install system dependencies
        timeout-minutes: 15
        run: |
          set -e  # Exit on any error

          # Update package list first
          sudo apt update

          # Install basic dependencies first (these are fast and reliable)
          sudo apt install -y cmake python3-pip git wget curl bc

          # Install Clang 18 with timeout and retry logic
          echo "Installing Clang 18..."
          for i in {1..3}; do
            if timeout 10m bash -c "
              wget -q https://apt.llvm.org/llvm.sh &&
              chmod +x llvm.sh &&
              sudo ./llvm.sh 18
            "; then
              echo "LLVM installation successful on attempt $i"
              break
            else
              echo "LLVM installation attempt $i failed, retrying..."
              rm -f llvm.sh
              if [ $i -eq 3 ]; then
                echo "All LLVM installation attempts failed"
                exit 1
              fi
              sleep 30
            fi
          done

          # Install code coverage tools
          sudo apt install -y llvm-18 llvm-18-dev clang-format-18 || {
            echo "Some LLVM tools not available, trying alternatives..."
            sudo apt install -y llvm llvm-dev clang-format || echo "Some tools installation failed"
          }

          # Set up symlinks
          sudo ln -sf /usr/bin/clang-18 /usr/bin/clang
          sudo ln -sf /usr/bin/clang++-18 /usr/bin/clang++
          sudo ln -sf /usr/bin/llvm-profdata-18 /usr/bin/llvm-profdata || sudo ln -sf /usr/bin/llvm-profdata /usr/bin/llvm-profdata
          sudo ln -sf /usr/bin/llvm-cov-18 /usr/bin/llvm-cov || sudo ln -sf /usr/bin/llvm-cov /usr/bin/llvm-cov
          if command -v clang-format-18 >/dev/null 2>&1; then
            sudo ln -sf /usr/bin/clang-format-18 /usr/bin/clang-format
          fi

          # Verify installation
          clang --version
          clang++ --version
          llvm-profdata-18 --version || echo "llvm-profdata not available"
          llvm-cov-18 --version || echo "llvm-cov not available"

      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: "3.11"

      - name: Install Conan
        run: |
          pip3 install --user conan
          echo "$HOME/.local/bin" >> $GITHUB_PATH

      - name: Setup Conan profile
        run: |
          conan profile detect --force
          # Use static profile for Clang 18 with C++23 (code coverage)
          sed -i 's/compiler=.*/compiler=clang/' ~/.conan2/profiles/default
          sed -i 's/compiler.version=.*/compiler.version=18/' ~/.conan2/profiles/default
          sed -i 's/compiler.libcxx=.*/compiler.libcxx=libstdc++11/' ~/.conan2/profiles/default
          sed -i 's/compiler.cppstd=.*/compiler.cppstd=23/' ~/.conan2/profiles/default
          sed -i 's/os=.*/os=Linux/' ~/.conan2/profiles/default
          sed -i 's/arch=.*/arch=x86_64/' ~/.conan2/profiles/default
          echo "=== Conan Profile ==="
          conan profile show --profile:host=default

      - name: Cache Conan packages
        uses: actions/cache@v4
        with:
          path: ~/.conan2
          key: conan-linux-clang-coverage-${{ hashFiles('conanfile.py') }}
          restore-keys: |
            conan-linux-clang-coverage-
            conan-linux-clang-

      - name: Install dependencies
        run: |
          export CC=clang
          export CXX=clang++
          conan install . -s os=Linux -s build_type=Debug --output-folder=build --build=missing -o with_gperftools=True

      - name: Configure CMake with Coverage
        run: |
          export CC=clang
          export CXX=clang++
          cmake -S . -B build/Coverage \
            -DCMAKE_TOOLCHAIN_FILE=build/conan_toolchain.cmake \
            -DCMAKE_BUILD_TYPE=Debug \
            -DCMAKE_CXX_COMPILER=clang++ \
            -DCMAKE_C_COMPILER=clang \
            -DCOMPILER_TYPE=CLANG \
            -DUSE_LTO=OFF \
            -DUSE_NATIVE_ARCH=OFF \
            -DENABLE_SHARED_LIBRARY=ON \
            -DUTF_STRINGS_BUILD_TESTS=ON \
            -DUTF_STRINGS_BUILD_BENCHMARKS=OFF \
            -DUTF_STRINGS_BUILD_FUZZ_TESTS=OFF \
            -DUTF_STRINGS_WITH_GPERFTOOLS=OFF \
            -DCMAKE_CXX_FLAGS="--coverage -fprofile-instr-generate -fcoverage-mapping" \
            -DCMAKE_C_FLAGS="--coverage -fprofile-instr-generate -fcoverage-mapping" \
            -DCMAKE_EXE_LINKER_FLAGS="--coverage"

      - name: Build with Coverage
        run: cmake --build build/Coverage --parallel

      - name: Run Tests with Coverage
        run: |
          cd build/Coverage
          # Set up coverage data collection
          export LLVM_PROFILE_FILE="utf_strings_coverage.profraw"

          # Run the tests
          ./utf_strings-tests --gtest_output=xml:test_results_coverage.xml

          # Verify coverage data was generated
          ls -la *.profraw || echo "No .profraw files found"

      - name: Process Coverage Data
        run: |
          cd build/Coverage

          # Convert raw profile data to indexed format
          if [ -f "utf_strings_coverage.profraw" ]; then
            echo "Converting coverage data..."
            # Try versioned commands first, fall back to unversioned
            if command -v llvm-profdata-18 >/dev/null 2>&1; then
              LLVM_PROFDATA=llvm-profdata-18
              LLVM_COV=llvm-cov-18
            else
              LLVM_PROFDATA=llvm-profdata
              LLVM_COV=llvm-cov
            fi
            
            $LLVM_PROFDATA merge -sparse utf_strings_coverage.profraw -o utf_strings_coverage.profdata
            
            # Generate coverage report in text format
            echo "Generating text coverage report..."
            $LLVM_COV report ./utf_strings-tests \
              -instr-profile=utf_strings_coverage.profdata \
              -ignore-filename-regex="(test|gtest|benchmark|conan|build)" \
              > coverage_report.txt
            
            # Generate detailed coverage report in HTML format
            echo "Generating HTML coverage report..."
            $LLVM_COV show ./utf_strings-tests \
              -instr-profile=utf_strings_coverage.profdata \
              -format=html \
              -output-dir=coverage_html \
              -ignore-filename-regex="(test|gtest|benchmark|conan|build)" \
              -show-line-counts-or-regions \
              -show-instantiations
            
            # Generate coverage summary in JSON format
            echo "Generating JSON coverage summary..."
            $LLVM_COV export ./utf_strings-tests \
              -instr-profile=utf_strings_coverage.profdata \
              -format=text \
              -ignore-filename-regex="(test|gtest|benchmark|conan|build)" \
              > coverage_summary.json
            
            # Display coverage summary
            echo "=== Coverage Summary ==="
            cat coverage_report.txt
            echo "========================"
            
          else
            echo "❌ No coverage data found!"
            echo "Available files:"
            ls -la
            exit 1
          fi

      - name: Generate Coverage Badge Data
        run: |
          cd build/Coverage
          if [ -f "coverage_summary.json" ]; then
            # Extract coverage percentage from JSON report
            COVERAGE=$(python3 -c "
          import json
          import sys
          try:
              with open('coverage_summary.json', 'r') as f:
                  data = json.load(f)
              
              # Extract totals from llvm-cov JSON format
              totals = data['data'][0]['totals']
              lines = totals['lines']
              covered = lines['covered']
              count = lines['count']
              
              if count > 0:
                  percentage = round((covered / count) * 100, 1)
                  print(f'{percentage}')
              else:
                  print('0.0')
          except Exception as e:
              print(f'Error: {e}', file=sys.stderr)
              print('0.0')
          ")
            
            echo "COVERAGE_PERCENTAGE=$COVERAGE" >> $GITHUB_ENV
            echo "Coverage: $COVERAGE%"
            
            # Create badge color based on coverage percentage
            if (( $(echo "$COVERAGE >= 90" | bc -l) )); then
              BADGE_COLOR="brightgreen"
            elif (( $(echo "$COVERAGE >= 80" | bc -l) )); then
              BADGE_COLOR="green"  
            elif (( $(echo "$COVERAGE >= 70" | bc -l) )); then
              BADGE_COLOR="yellowgreen"
            elif (( $(echo "$COVERAGE >= 60" | bc -l) )); then
              BADGE_COLOR="yellow"
            elif (( $(echo "$COVERAGE >= 50" | bc -l) )); then
              BADGE_COLOR="orange"
            else
              BADGE_COLOR="red"
            fi
            
            echo "BADGE_COLOR=$BADGE_COLOR" >> $GITHUB_ENV
            
            # Create a simple coverage summary for artifact
            cat > coverage_summary.txt << EOF
          UTF Strings Library - Code Coverage Report
          ==========================================
          Generated: $(date)
          Build: Clang Debug with Coverage
          Test Suite: All unit tests

          Coverage: $COVERAGE%
          Badge Color: $BADGE_COLOR

          Detailed reports available in coverage_html/ directory
          EOF
            
          else
            echo "COVERAGE_PERCENTAGE=0.0" >> $GITHUB_ENV
            echo "BADGE_COLOR=red" >> $GITHUB_ENV
          fi

      - name: Upload Coverage Reports
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: coverage-reports-linux-clang
          path: |
            build/Coverage/coverage_report.txt
            build/Coverage/coverage_summary.json
            build/Coverage/coverage_summary.txt
            build/Coverage/coverage_html/
            build/Coverage/test_results_coverage.xml
          retention-days: 30

      - name: Upload Coverage to Codecov (Optional)
        uses: codecov/codecov-action@v3
        if: always()
        with:
          files: build/Coverage/coverage_summary.json
          flags: unittests
          name: utf-strings-coverage
          fail_ci_if_error: false
          verbose: true

      - name: Comment Coverage on PR
        if: github.event_name == 'pull_request'
        uses: actions/github-script@v7
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          script: |
            const coverage = process.env.COVERAGE_PERCENTAGE;
            const badgeColor = process.env.BADGE_COLOR;

            const comment = `## 📊 Code Coverage Report

            **Coverage:** ${coverage}%

            ![Coverage Badge](https://img.shields.io/badge/coverage-${coverage}%25-${badgeColor})

            <details>
            <summary>📋 Coverage Details</summary>

            - **Build:** Clang Debug with Coverage Instrumentation
            - **Test Suite:** All unit tests (65 tests across 22 test suites)
            - **Generated:** ${new Date().toISOString()}

            📁 **Artifacts Generated:**
            - 📄 Text report: \`coverage_report.txt\`
            - 🌐 HTML report: \`coverage_html/index.html\` 
            - 📊 JSON summary: \`coverage_summary.json\`
            - ✅ Test results: \`test_results_coverage.xml\`

            </details>

            > 💡 **Tip:** Download the coverage artifacts to view detailed line-by-line coverage reports.`;

            try {
              await github.rest.issues.createComment({
                issue_number: context.issue.number,
                owner: context.repo.owner,
                repo: context.repo.repo,
                body: comment
              });
              console.log('✅ Coverage comment posted successfully');
            } catch (error) {
              console.log('❌ Failed to post coverage comment:', error.message);
              console.log('This is likely due to insufficient permissions or the PR being from a fork');
            }

  # ============================================================================
  # Linux x64 - Clang with Fuzz Testing
  # ============================================================================

  linux-clang-fuzz:
    name: "Linux Clang Fuzz Testing (x64)"
    runs-on: ubuntu-24.04
    needs: [yaml-validation]
    if: always() && (needs.yaml-validation.result == 'success' || needs.yaml-validation.result == 'skipped')

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

      - name: Install system dependencies
        timeout-minutes: 15
        run: |
          set -e  # Exit on any error

          # Update package list first
          sudo apt update

          # Install basic dependencies first (these are fast and reliable)
          sudo apt install -y cmake python3-pip git wget curl

          # Install Clang 18 with timeout and retry logic
          echo "Installing Clang 18..."
          for i in {1..3}; do
            if timeout 10m bash -c "
              wget -q https://apt.llvm.org/llvm.sh &&
              chmod +x llvm.sh &&
              sudo ./llvm.sh 18
            "; then
              echo "LLVM installation successful on attempt $i"
              break
            else
              echo "LLVM installation attempt $i failed, retrying..."
              rm -f llvm.sh
              if [ $i -eq 3 ]; then
                echo "All LLVM installation attempts failed"
                exit 1
              fi
              sleep 30
            fi
          done

          # Install additional tools
          sudo apt install -y clang-format-18 || {
            echo "clang-format-18 not available, trying alternatives..."
            sudo apt install -y clang-format || echo "clang-format installation failed"
          }

          # Set up symlinks
          sudo ln -sf /usr/bin/clang-18 /usr/bin/clang
          sudo ln -sf /usr/bin/clang++-18 /usr/bin/clang++
          if command -v clang-format-18 >/dev/null 2>&1; then
            sudo ln -sf /usr/bin/clang-format-18 /usr/bin/clang-format
          fi

          # Verify installation
          clang --version
          clang++ --version

      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: "3.11"

      - name: Install Conan
        run: |
          pip3 install --user conan
          echo "$HOME/.local/bin" >> $GITHUB_PATH

      - name: Setup Conan profile
        run: |
          conan profile detect --force
          # Use static profile for Clang 18 with C++23 (fuzz testing)
          sed -i 's/compiler=.*/compiler=clang/' ~/.conan2/profiles/default
          sed -i 's/compiler.version=.*/compiler.version=18/' ~/.conan2/profiles/default
          sed -i 's/compiler.libcxx=.*/compiler.libcxx=libstdc++11/' ~/.conan2/profiles/default
          sed -i 's/compiler.cppstd=.*/compiler.cppstd=23/' ~/.conan2/profiles/default
          sed -i 's/os=.*/os=Linux/' ~/.conan2/profiles/default
          sed -i 's/arch=.*/arch=x86_64/' ~/.conan2/profiles/default
          echo "=== Conan Profile ==="
          conan profile show --profile:host=default

      - name: Cache Conan packages
        uses: actions/cache@v4
        with:
          path: ~/.conan2
          key: conan-linux-clang-fuzz-${{ hashFiles('conanfile.py') }}
          restore-keys: |
            conan-linux-clang-fuzz-
            conan-linux-clang-

      - name: Install dependencies
        run: |
          export CC=clang
          export CXX=clang++
          conan install . -s os=Linux -s build_type=Debug --output-folder=build --build=missing -o with_gperftools=True

      - name: Configure CMake with Fuzz Testing
        run: |
          export CC=clang
          export CXX=clang++
          cmake -S . -B build/Fuzz \
            -DCMAKE_TOOLCHAIN_FILE=build/conan_toolchain.cmake \
            -DCMAKE_BUILD_TYPE=Debug \
            -DCMAKE_CXX_COMPILER=clang++ \
            -DCOMPILER_TYPE=CLANG \
            -DUSE_LTO=OFF \
            -DUSE_NATIVE_ARCH=OFF \
            -DENABLE_SHARED_LIBRARY=OFF \
            -DUTF_STRINGS_BUILD_TESTS=OFF \
            -DUTF_STRINGS_BUILD_BENCHMARKS=OFF \
            -DUTF_STRINGS_BUILD_FUZZ_TESTS=ON \
            -DUTF_STRINGS_WITH_GPERFTOOLS=OFF

      - name: Build Fuzz Targets
        run: cmake --build build/Fuzz --parallel

      - name: Run Fuzz Tests (Short Duration for CI)
        run: |
          cd build/Fuzz
          echo "Running UTF-8 fuzz tests..."
          timeout 60s ./fuzz_utf8 -max_total_time=30 -print_final_stats=1 || true
          echo "Running UTF-16 BE fuzz tests..."
          timeout 60s ./fuzz_utf16_be -max_total_time=30 -print_final_stats=1 || true
          echo "Running UTF-16 LE fuzz tests..."
          timeout 60s ./fuzz_utf16_le -max_total_time=30 -print_final_stats=1 || true
          echo "Running UTF-32 BE fuzz tests..."
          timeout 60s ./fuzz_utf32_be -max_total_time=30 -print_final_stats=1 || true
          echo "Running UTF-32 LE fuzz tests..."
          timeout 60s ./fuzz_utf32_le -max_total_time=30 -print_final_stats=1 || true

      - name: Upload fuzz artifacts
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: fuzz-results-linux-clang
          path: |
            build/Fuzz/*.log
            build/Fuzz/crash-*
            build/Fuzz/leak-*
            build/Fuzz/timeout-*

  # ============================================================================
  # Linux x64 - Sanitizer Testing (GCC & Clang)
  # ============================================================================

  linux-sanitizers:
    name: "Linux Sanitizer Testing (x64)"
    runs-on: ubuntu-24.04
    needs: [yaml-validation]
    if: always() && (needs.yaml-validation.result == 'success' || needs.yaml-validation.result == 'skipped')
    strategy:
      matrix:
        sanitizer: [asan, tsan]
        compiler: [clang]

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

      - name: Install system dependencies
        timeout-minutes: 15
        run: |
          set -e  # Exit on any error

          # Update package list first
          sudo apt update

          # Install basic dependencies first
          sudo apt install -y cmake python3-pip git wget curl

          # Install Clang 18 with retry logic (sanitizers use Clang only)
          echo "Installing Clang 18..."
          for i in {1..3}; do
            if timeout 10m bash -c "
              wget -q https://apt.llvm.org/llvm.sh &&
              chmod +x llvm.sh &&
              sudo ./llvm.sh 18
            "; then
              echo "LLVM installation successful on attempt $i"
              sudo ln -sf /usr/bin/clang-18 /usr/bin/clang
              sudo ln -sf /usr/bin/clang++-18 /usr/bin/clang++
              break
            else
              echo "LLVM installation attempt $i failed, retrying..."
              rm -f llvm.sh
              if [ $i -eq 3 ]; then
                echo "All LLVM installation attempts failed"
                exit 1
              fi
              sleep 30
            fi
          done

          # Verify Clang installation
          clang --version
          clang++ --version

      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: "3.11"

      - name: Install Conan
        run: |
          pip3 install --user conan
          echo "$HOME/.local/bin" >> $GITHUB_PATH

      - name: Setup Conan profile
        run: |
          conan profile detect --force
          # Use static profile for Clang 18 with C++23 (sanitizers use Clang only)
          sed -i 's/compiler=.*/compiler=clang/' ~/.conan2/profiles/default
          sed -i 's/compiler.version=.*/compiler.version=18/' ~/.conan2/profiles/default
          sed -i 's/compiler.libcxx=.*/compiler.libcxx=libstdc++11/' ~/.conan2/profiles/default
          sed -i 's/compiler.cppstd=.*/compiler.cppstd=23/' ~/.conan2/profiles/default
          sed -i 's/os=.*/os=Linux/' ~/.conan2/profiles/default
          sed -i 's/arch=.*/arch=x86_64/' ~/.conan2/profiles/default
          echo "=== Conan Profile ==="
          conan profile show --profile:host=default

      - name: Cache Conan packages
        uses: actions/cache@v4
        with:
          path: ~/.conan2
          key: conan-linux-clang-${{ matrix.sanitizer }}-${{ hashFiles('conanfile.py') }}
          restore-keys: |
            conan-linux-clang-${{ matrix.sanitizer }}-

      - name: Install dependencies
        run: |
          export CC=clang
          export CXX=clang++
          conan install . -s os=Linux -s build_type=Debug --output-folder=build --build=missing -o with_gperftools=True

      - name: Configure CMake with Sanitizers
        run: |
          export CC=clang
          export CXX=clang++

          if [ "${{ matrix.sanitizer }}" = "asan" ]; then
            cmake --preset conan-debug \
              -DCOMPILER_TYPE=CLANG \
              -DUSE_LTO=OFF \
              -DUSE_NATIVE_ARCH=OFF \
              -DENABLE_SHARED_LIBRARY=ON \
              -DUTF_STRINGS_ENABLE_SANITIZERS=ON
          else
            cmake --preset conan-debug \
              -DCOMPILER_TYPE=CLANG \
              -DUSE_LTO=OFF \
              -DUSE_NATIVE_ARCH=OFF \
              -DENABLE_SHARED_LIBRARY=ON \
              -DUTF_STRINGS_ENABLE_THREAD_SANITIZER=ON
          fi

      - name: Build with Sanitizers
        run: cmake --build --preset conan-debug --parallel

      - name: Test with Sanitizers
        run: |
          # Debug builds use build/build directory with Conan presets
          cd build/build
          ./utf_strings-tests --gtest_output=xml:test_results_clang_${{ matrix.sanitizer }}.xml

      - name: Upload sanitizer results
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: sanitizer-results-clang-${{ matrix.sanitizer }}
          path: build/build/test_results_clang_${{ matrix.sanitizer }}.xml

  # ============================================================================
  # Windows x64 - MSVC 2022
  # ============================================================================

  windows-msvc:
    name: "Windows ${{ matrix.compiler_name }} (x64)"
    runs-on: windows-2022
    timeout-minutes: 30
    needs: [yaml-validation]
    if: always() && (needs.yaml-validation.result == 'success' || needs.yaml-validation.result == 'skipped')
    strategy:
      matrix:
        build_type: [Release] # Debug builds timeout on Windows CI
        compiler: [msvc, clang-cl]
        include:
          - compiler: msvc
            compiler_name: "MSVC 2022"
            conan_compiler: msvc
            conan_version: 193
            runtime_version: ""
            cmake_args: "-DUSE_MSVC_LTO=ON -DENABLE_SHARED_LIBRARY=ON"
          - compiler: clang-cl
            compiler_name: "Clang-CL"
            conan_compiler: clang
            conan_version: 16
            runtime_version: "v143"
            cmake_args: "-DCMAKE_CXX_COMPILER=clang-cl -DCMAKE_C_COMPILER=clang-cl -DUSE_MSVC_LTO=OFF -DENABLE_SHARED_LIBRARY=OFF"

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

      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: "3.11"

      - name: Install Conan
        run: |
          pip install conan

      - name: Setup Conan profile
        run: |
          conan profile detect --force
          # Configure profile for ${{ matrix.compiler_name }} with C++23
          $profile = "$env:USERPROFILE\.conan2\profiles\default"
          (Get-Content $profile) -replace 'compiler=.*', 'compiler=${{ matrix.conan_compiler }}' | Set-Content $profile
          (Get-Content $profile) -replace 'compiler\.version=.*', 'compiler.version=${{ matrix.conan_version }}' | Set-Content $profile
          (Get-Content $profile) -replace 'compiler\.runtime=.*', 'compiler.runtime=dynamic' | Set-Content $profile
          (Get-Content $profile) -replace 'compiler\.cppstd=.*', 'compiler.cppstd=23' | Set-Content $profile
          (Get-Content $profile) -replace 'os=.*', 'os=Windows' | Set-Content $profile
          (Get-Content $profile) -replace 'arch=.*', 'arch=x86_64' | Set-Content $profile
          # Add runtime_version for Clang builds (required for Windows Clang-CL)
          if ("${{ matrix.runtime_version }}" -ne "") {
            Add-Content $profile "compiler.runtime_version=${{ matrix.runtime_version }}"
          }
          Write-Host "=== ${{ matrix.compiler_name }} Conan Profile ==="
          conan profile show --profile:host=default
        shell: pwsh

      - name: Cache Conan packages
        uses: actions/cache@v4
        with:
          path: ~/.conan2
          key: conan-windows-${{ matrix.compiler }}-${{ matrix.build_type }}-${{ hashFiles('conanfile.py') }}
          restore-keys: |
            conan-windows-${{ matrix.compiler }}-${{ matrix.build_type }}-
            conan-windows-${{ matrix.compiler }}-

      - name: Install LLVM (for clang-format)
        run: |
          choco install llvm -y

      - name: Setup MSVC environment
        uses: ilammy/msvc-dev-cmd@v1
        with:
          arch: x64

      - name: Clean build directory
        run: |
          # Clean build directory to prevent configuration conflicts between matrix jobs
          if (Test-Path "build") {
            Remove-Item -Recurse -Force "build"
          }
        shell: pwsh

      - name: Install dependencies
        timeout-minutes: 20
        run: |
          # Install Conan dependencies for Windows ${{ matrix.compiler_name }}
          conan install . -s os=Windows -s build_type=${{ matrix.build_type }} --output-folder=build --build=missing -o with_gperftools=False

      - name: Configure CMake
        run: |
          # Windows: Configure with ${{ matrix.compiler_name }} compiler using compiler-specific preset logic
          if ("${{ matrix.compiler }}" -eq "msvc") {
            # MSVC always uses conan-default for configure
            $preset = "conan-default"
          } else {
            # Clang-CL uses build-type specific presets
            $preset = if ("${{ matrix.build_type }}" -eq "Debug") { "conan-debug" } else { "conan-release" }
          }
          # Override generator for Windows builds to ensure Visual Studio generator is used
          # Force C++23 standard for MSVC
          cmake --preset $preset -G "Visual Studio 17 2022" -A x64 -DCMAKE_CXX_STANDARD=23 -DCMAKE_CXX_FLAGS="/std:c++latest /Zc:__cplusplus" ${{ matrix.cmake_args }}

      - name: Build
        run: |
          # Windows: Use build-type specific build preset
          $preset = if ("${{ matrix.build_type }}" -eq "Debug") { "conan-debug" } else { "conan-release" }
          cmake --build --preset $preset --config ${{ matrix.build_type }} --parallel

      - name: Test
        run: |
          # Windows builds use configuration-specific subdirectories
          cd build\build\${{ matrix.build_type }}
          if ("${{ matrix.build_type }}" -eq "Debug") {
            .\utf_strings-tests.exe --gtest_output=xml:test_results_${{ matrix.compiler }}_debug.xml
          } else {
            .\utf_strings-tests.exe --gtest_output=xml:test_results_${{ matrix.compiler }}_release.xml
          }

      - name: Benchmark (Release only)
        if: matrix.build_type == 'Release'
        run: |
          cd build\build\Release
          .\utf_strings-bench.exe --benchmark_min_time=0.1s --benchmark_format=json --benchmark_out=benchmark_results_${{ matrix.compiler }}.json

      - name: Check code formatting (Release only)
        if: matrix.build_type == 'Release'
        run: |
          $env:PATH = "C:\Program Files\LLVM\bin;$env:PATH"
          cmake --build --preset conan-release --config Release --target format-check

      - name: Upload test results
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: test-results-windows-${{ matrix.compiler }}-${{ matrix.build_type }}
          path: |
            build\build\Debug\test_results_${{ matrix.compiler }}_debug.xml
            build\build\Release\test_results_${{ matrix.compiler }}_release.xml
            build\build\Release\benchmark_results_${{ matrix.compiler }}.json

  # ============================================================================
  # Windows - MSVC with AddressSanitizer
  # ============================================================================

  windows-msvc-debug:
    name: "Windows MSVC Debug (x64)"
    runs-on: windows-2022
    timeout-minutes: 30
    needs: [yaml-validation]
    if: always() && (needs.yaml-validation.result == 'success' || needs.yaml-validation.result == 'skipped')

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

      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: "3.11"

      - name: Install Conan
        run: |
          pip install conan

      - name: Setup Conan profile
        run: |
          conan profile detect --force
          # Use static profile for MSVC 2022 with C++23 (sanitizer)
          $profile = "$env:USERPROFILE\.conan2\profiles\default"
          (Get-Content $profile) -replace 'compiler=.*', 'compiler=msvc' | Set-Content $profile
          (Get-Content $profile) -replace 'compiler\.version=.*', 'compiler.version=193' | Set-Content $profile
          (Get-Content $profile) -replace 'compiler\.runtime=.*', 'compiler.runtime=dynamic' | Set-Content $profile
          (Get-Content $profile) -replace 'compiler\.cppstd=.*', 'compiler.cppstd=23' | Set-Content $profile
          (Get-Content $profile) -replace 'os=.*', 'os=Windows' | Set-Content $profile
          (Get-Content $profile) -replace 'arch=.*', 'arch=x86_64' | Set-Content $profile
          Write-Host "=== Conan Profile ==="
          conan profile show --profile:host=default
        shell: pwsh

      - name: Cache Conan packages
        uses: actions/cache@v4
        with:
          path: ~/.conan2
          key: conan-windows-msvc-asan-${{ hashFiles('conanfile.py') }}
          restore-keys: |
            conan-windows-msvc-asan-
            conan-windows-msvc-

      - name: Setup MSVC environment
        uses: ilammy/msvc-dev-cmd@v1
        with:
          arch: x64

      - name: Clean build directory
        run: |
          # Clean build directory to prevent configuration conflicts
          if (Test-Path "build") {
            Remove-Item -Recurse -Force "build"
          }
        shell: pwsh

      - name: Install dependencies
        timeout-minutes: 20
        run: |
          # Optimize Conan builds for CI
          conan config set tools.build:jobs=2
          conan config set tools.build:verbosity=minimal
          conan install . -s os=Windows -s build_type=Debug --output-folder=build --build=missing -o with_gperftools=False

      - name: Configure CMake (Debug build without AddressSanitizer)
        run: |
          # Note: Windows AddressSanitizer disabled due to Conan dependency linking issues
          # (annotate_string/annotate_vector mismatch between ASAN and non-ASAN builds)
          # AddressSanitizer testing is comprehensively covered by Linux CI jobs
          # Override generator for Windows builds to ensure Visual Studio generator is used
          # Force C++23 standard for MSVC
          cmake --preset conan-default -G "Visual Studio 17 2022" -A x64 -DCMAKE_CXX_STANDARD=23 -DCMAKE_CXX_FLAGS="/std:c++latest /Zc:__cplusplus"

      - name: Build Debug
        run: cmake --build --preset conan-debug --config Debug --parallel

      - name: Test Debug Build
        run: |
          cd build\build\Debug
          .\utf_strings-tests.exe --gtest_output=xml:test_results_msvc_debug.xml

      - name: Upload debug test results
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: test-results-windows-msvc-debug
          path: build\build\Debug\test_results_msvc_debug.xml

  # ============================================================================
  # Publish Test Results
  # ============================================================================

  publish-test-results:
    name: "Publish Test Results"
    runs-on: ubuntu-latest
    needs:
      [
        linux-gcc,
        linux-clang,
        linux-clang-coverage,
        windows-msvc,
        linux-sanitizers,
        windows-msvc-debug,
      ]
    if: always()
    permissions:
      contents: read
      issues: read
      checks: write
      pull-requests: write

    steps:
      - name: Download all artifacts
        uses: actions/download-artifact@v4

      - name: Publish Unit Test Results
        uses: EnricoMi/publish-unit-test-result-action@v2
        if: always()
        with:
          files: "**/*.xml"
          comment_mode: always
          check_name: "Unit Test Results"
          report_individual_runs: true
          deduplicate_classes_by_file_name: false

  # ============================================================================
  # Documentation Build for GitHub Pages
  # ============================================================================

  build-docs:
    name: "Build Documentation"
    runs-on: ubuntu-latest
    needs: [yaml-validation]
    if: always() && (needs.yaml-validation.result == 'success' || needs.yaml-validation.result == 'skipped') && github.ref == 'refs/heads/main'

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

      - name: Validate docs directory
        run: |
          echo "🔍 Validating documentation structure..."

          if [ ! -d "docs" ]; then
            echo "❌ docs/ directory not found!"
            exit 1
          fi

          if [ ! -f "docs/index.html" ] && [ ! -f "docs/index.md" ]; then
            echo "❌ No index.html or index.md found in docs/"
            exit 1
          fi

          echo "✅ Documentation structure validation passed"
          echo ""
          echo "📁 Documentation contents:"
          find docs/ -type f | sort

      - name: Prepare documentation for Jekyll
        run: |
          echo "🔧 Preparing documentation for Jekyll processing..."

          # Ensure proper Jekyll configuration exists
          if [ ! -f "docs/_config.yml" ]; then
            echo "⚠️  No _config.yml found, creating default configuration..."
            cat > docs/_config.yml << 'EOF'
          title: UTF Strings Documentation
          description: High-performance UTF string processing library for C++
          remote_theme: pages-themes/primer
          plugins:
            - jekyll-remote-theme

          # Build settings
          markdown: kramdown
          highlighter: rouge

          # Navigation
          header_pages:
            - index.html
            - README.md

          # Enable GitHub metadata
          github: [metadata]
          EOF
          fi

          # Create assets directory and CSS if needed
          mkdir -p docs/assets/css

          if [ ! -f "docs/assets/css/style.scss" ]; then
            echo "🎨 Creating custom CSS override..."
            cat > docs/assets/css/style.scss << 'EOF'
          ---
          ---

          @import "{{ site.theme }}";

          /* Custom styles for UTF Strings documentation */
          .main-content {
            max-width: 1200px;
          }

          code {
            background-color: #f6f8fa;
            border-radius: 3px;
            padding: 0.2em 0.4em;
          }

          pre code {
            background-color: transparent;
            padding: 0;
          }
          EOF
          fi

          echo "✅ Jekyll preparation completed"

      - name: Create documentation artifact
        run: |
          echo "📦 Creating documentation artifact..."

          # Create a clean copy of docs for artifact
          rm -rf docs-artifact/
          cp -r docs/ docs-artifact/

          # Remove any Jekyll build artifacts from source
          rm -rf docs-artifact/_site docs-artifact/.jekyll-cache docs-artifact/.sass-cache

          # Set proper permissions
          chmod -R 755 docs-artifact/
          find docs-artifact/ -type f -exec chmod 644 {} \;

          echo "📄 Final artifact contents:"
          find docs-artifact/ -type f | sort

      - name: Upload docs artifact for Pages
        uses: actions/upload-artifact@v4
        with:
          name: docs-for-pages
          path: docs-artifact/
          retention-days: 1
          if-no-files-found: error

      - name: Documentation build summary
        run: |
          echo "✅ Documentation build completed successfully!"
          echo "📦 Artifact 'docs-for-pages' created and uploaded"
          echo "🎯 Ready for GitHub Pages deployment"
          echo ""
          echo "📋 Build details:"
          echo "- Jekyll configuration: $([ -f 'docs/_config.yml' ] && echo 'Present' || echo 'Missing')"
          echo "- Custom CSS: $([ -f 'docs/assets/css/style.scss' ] && echo 'Present' || echo 'Default')"
          echo "- Theme: $(grep 'remote_theme\|theme:' docs/_config.yml 2>/dev/null | cut -d':' -f2 | tr -d ' ' || echo 'Default')"