CI.yml

# GitHub Actions docs
# https://help.github.com/en/articles/about-github-actions
# https://help.github.com/en/articles/workflow-syntax-for-github-actions

name: Validate Docs

on: [pull_request]

# A new push supersedes the run before it.
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

env:
  NODE_VERSION: 24

jobs:
  # Needs no dependencies, so it reports in seconds rather than queueing behind
  # npm ci and lint.
  admonitions:
    name: Check Admonitions
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      with:
        # The check diffs against the pull request base, so it needs history.
        fetch-depth: 0
    - uses: ./.github/workflows/actions/check-admonitions

  # These produce the same verdict on any operating system, so they run once.
  checks:
    name: Checks
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
    - name: ⚙️ Use Node.js
      uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
      with:
        node-version: ${{ env.NODE_VERSION }}
        cache: npm
    - name: 🕸️ Install Dependencies
      run: npm ci
    - name: Test
      run: npm run test
    - name: 🧩 Typecheck
      run: npm run typecheck
    - name: 🔤 Spell Check
      run: npm run spellcheck
    # Docusaurus derives a heading's anchor from its text, so renaming a
    # heading moves the anchor and breaks every inbound link. An explicit id
    # survives the rename, and lets a translation keep the English anchor
    # after the heading text is translated.
    #
    # Nothing in Docusaurus enforces this: a page whose headings are all
    # unpinned builds clean. So run its own generator and fail if it had
    # anything to add.
    - name: 🔗 Heading IDs
      run: |
        npm run heading-ids
        if ! git diff --quiet -- docs; then
          echo "::error::Headings are missing explicit ids. Run \`npm run heading-ids\` and commit the result."
          git diff -- docs
          exit 1
        fi
    - uses: ./.github/workflows/actions/check-translations

  cross-platform:
    name: Cross-platform on ${{ matrix.os }}
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        # Prettier rewrites line endings, so Lint is the one check whose
        # verdict depends on the operating system.
        os: [windows-latest, macOS-latest]

    steps:
    - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
    - name: ⚙️ Use Node.js
      uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
      with:
        node-version: ${{ env.NODE_VERSION }}
        cache: npm
    - name: 🕸️ Install Dependencies
      run: npm ci
    - name: 🖌️ Lint
      run: npm run lint
    # Lint changes should be pushed to the branch before the branch is merge
    # eligible.
    - name: 🔍 Check Diff
      run: git diff --exit-code
      shell: bash

  verify:
    # The one required check on main and the feature branches, so the jobs
    # above can change without touching the protection rules. Renaming this
    # blocks merges until those rules are updated to match.
    name: Verify
    if: ${{ always() }}
    needs: [admonitions, checks, cross-platform]
    runs-on: ubuntu-latest

    steps:
    - name: Check job status
      if: ${{ contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled') }}
      run: exit 1