deploy-docs.yml

name: Deploy Docs to GitHub Pages

on:
  workflow_dispatch:
    inputs:
      release_tag:
        description: 'Published release tag to deploy, for example v3.0.0'
        required: true
        type: string

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout release
        uses: actions/checkout@v4
        with:
          ref: ${{ inputs.release_tag }}
          path: release

      - name: Checkout release tooling
        uses: actions/checkout@v4
        with:
          ref: ${{ github.sha }}
          path: tooling

      - name: Verify tag, package and npm registry agree
        shell: bash
        run: |
          RELEASE_TAG='${{ inputs.release_tag }}'
          if [[ ! "${RELEASE_TAG}" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
            echo "::error::release_tag must be an exact stable SemVer tag such as v3.0.0"
            exit 1
          fi

          PACKAGE_VERSION=$(node -p "require('./release/package.json').version")
          TAG_VERSION=${RELEASE_TAG#v}
          REGISTRY_VERSION=$(npm view "monsqlize@${PACKAGE_VERSION}" version --registry=https://registry.npmjs.org/)
          if [ "${TAG_VERSION}" != "${PACKAGE_VERSION}" ] || [ "${REGISTRY_VERSION}" != "${PACKAGE_VERSION}" ]; then
            echo "::error::tag=${TAG_VERSION}, package=${PACKAGE_VERSION}, registry=${REGISTRY_VERSION} must match"
            exit 1
          fi

          echo "DOCS_RELEASE_VERSION=${PACKAGE_VERSION}" >> "${GITHUB_ENV}"
          echo "DOCS_RELEASE_CHANNEL=stable" >> "${GITHUB_ENV}"

      - name: Select verified website toolchain
        shell: bash
        run: |
          if node -e "process.exit(require('./release/website/package.json').scripts?.verify ? 0 : 1)"; then
            echo "DOCS_LEGACY_TAG=false" >> "${GITHUB_ENV}"
          else
            cp tooling/website/package.json release/website/package.json
            cp tooling/website/package-lock.json release/website/package-lock.json
            echo "DOCS_LEGACY_TAG=true" >> "${GITHUB_ENV}"
          fi

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
          cache-dependency-path: release/website/package-lock.json

      - name: Check docs example matrix
        run: node release/scripts/validation/check-doc-example-matrix.cjs --require-covered

      - name: Install website dependencies
        working-directory: ./release/website
        run: npm ci

      - name: Verify docs site
        working-directory: ./release/website
        shell: bash
        run: |
          if [[ "${DOCS_LEGACY_TAG}" != "true" ]]; then
            npm run verify
          else
            npm run build
            node ../../tooling/scripts/validation/check-site-links.cjs --dist "${PWD}/dist"
            npm audit
          fi

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./release/website/dist

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

      - name: Summarize stable docs deployment
        shell: bash
        run: |
          {
            echo "## Stable documentation deployed"
            echo
            echo "Release tag: \`${{ inputs.release_tag }}\`"
            echo
            echo "Pages URL: ${{ steps.deployment.outputs.page_url }}"
          } >> "${GITHUB_STEP_SUMMARY}"