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@v5
        with:
          ref: ${{ inputs.release_tag }}
          path: release

      - name: Checkout release tooling
        uses: actions/checkout@v5
        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?.['check:browser'] ? 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@v6
        with:
          node-version: '22'
          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: Include site ownership verification
        shell: bash
        run: |
          node <<'NODE'
          const fs = require('node:fs');
          const { execFileSync } = require('node:child_process');
          const file = 'google4524eb8336ad041b.html';
          const source = `tooling/docs/public/${file}`;
          const sourceSha = execFileSync('git', ['-C', 'tooling', 'rev-parse', 'HEAD'], { encoding: 'utf8' }).trim();
          if (sourceSha !== process.env.GITHUB_SHA) {
            throw new Error('Verification source must match the workflow commit.');
          }
          if (fs.readFileSync(source, 'utf8').trimEnd() !== `google-site-verification: ${file}`) {
            throw new Error('Unexpected Google site verification content.');
          }
          // Site ownership is independent of the published documentation version.
          fs.copyFileSync(source, `release/docs/public/${file}`);
          fs.appendFileSync(process.env.GITHUB_STEP_SUMMARY,
            `\nSite verification file: ${file}\n\nVerification source commit: ${sourceSha}\n`);
          NODE

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

      - name: Install Chromium for current-site verification
        if: env.DOCS_LEGACY_TAG != 'true'
        working-directory: ./release/website
        run: npx playwright install --with-deps chromium

      - 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: Verify site ownership artifact
        shell: bash
        run: |
          node <<'NODE'
          const fs = require('node:fs');
          const { createHash } = require('node:crypto');
          const file = 'google4524eb8336ad041b.html';
          const source = fs.readFileSync(`tooling/docs/public/${file}`);
          const artifact = fs.readFileSync(`release/website/dist/${file}`);
          if (!source.equals(artifact)) {
            throw new Error('Built site verification file differs from its source.');
          }
          const sha256 = createHash('sha256').update(artifact).digest('hex');
          fs.appendFileSync(process.env.GITHUB_STEP_SUMMARY, `\nVerification file SHA-256: ${sha256}\n`);
          NODE

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v5
        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@v5

      - 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}"