name: Deploy Documentation

on:
  push:
    branches:
      - main
    paths:
      - 'documentation/**'

# Use same concurrency group as PR preview workflow to prevent race conditions
# when both workflows try to modify gh-pages branch simultaneously.
# cancel-in-progress: false ensures production deploys queue and wait rather than
# being cancelled by PR preview workflows.
concurrency:
  group: pr-preview
  cancel-in-progress: false

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: write

    steps:
      - name: Checkout the branch
        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8  # v6.0.1

      - name: Setup Node.js
        uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238  # v6.2.0
        with:
          node-version: 20 

      - name: Cache Node.js modules (documentation)
        uses: actions/cache@8b402f58fbc84540c8b491a91e594a4576fec3d7  # v5.0.2
        with:
          path: ./documentation/node_modules
          key: ${{ runner.os }}-documentation-${{ hashFiles('./documentation/package-lock.json') }}
          restore-keys: |
            ${{ runner.os }}-documentation-

      - name: Install dependencies and build docs
        working-directory: ./documentation
        env:
          INKEEP_API_KEY: ${{ secrets.INKEEP_API_KEY }}
          INKEEP_INTEGRATION_ID: ${{ secrets.INKEEP_INTEGRATION_ID }}
          INKEEP_ORG_ID: ${{ secrets.INKEEP_ORG_ID }}
        run: |
          npm install
          npm test
          npm run build

      - name: Verify docs map was generated
        working-directory: ./documentation
        run: ./scripts/verify-build.sh

      - name: Checkout gh-pages branch
        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
        continue-on-error: true      # Branch may not exist on first deploy or in forks
        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8  # v6.0.1
        with:
          ref: gh-pages
          path: gh-pages-current

      - name: Preserve pr-preview directory
        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
        run: |
          # Copy pr-preview from current gh-pages to the new build (if it exists)
          if [ -d "gh-pages-current/pr-preview" ]; then
            cp -r gh-pages-current/pr-preview documentation/build/pr-preview
            echo "Preserved pr-preview directory with $(ls gh-pages-current/pr-preview | wc -l) PR previews"
          else
            echo "No pr-preview directory to preserve"
          fi

      - name: Deploy to /gh-pages
        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
        uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e  # v4.0.0
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: documentation/build
          keep_files: false          # Clean deploy - only keep what's in the build + pr-preview
          force_orphan: true         # Create a fresh commit without history to prevent bloat