name: Deploy Site

on:
  push:
    branches: [main]
    paths:
      - "platforms/**"
      - "emulators/**"
      - "provenance/**"
      - "wiki/**"
      - "exports/**"
      # Every script the build runs or imports, and no other
      # (tests/test_workflow_paths.py).
      - "scripts/artifacts.py"
      - "scripts/auto_fetch.py"
      - "scripts/common.py"
      - "scripts/cross_reference.py"
      - "scripts/crypto_verify.py"
      - "scripts/derivations.py"
      - "scripts/deterministic_zip.py"
      - "scripts/dumpcatalog.py"
      - "scripts/exporter/baseline.py"
      - "scripts/exporter/candidates.py"
      - "scripts/gamedata.py"
      - "scripts/generate_pack.py"
      - "scripts/generate_readme.py"
      - "scripts/generate_site.py"
      - "scripts/hashing.py"
      - "scripts/largefiles.py"
      - "scripts/launchers.py"
      - "scripts/manifestselect.py"
      - "scripts/nativemode.py"
      - "scripts/packextras.py"
      - "scripts/packpaths.py"
      - "scripts/packreadme.py"
      - "scripts/packresolve.py"
      - "scripts/packverify.py"
      - "scripts/provenance_report.py"
      - "scripts/refresh_data_dirs.py"
      - "scripts/region.py"
      - "scripts/release_record.py"
      - "scripts/restore_large_files.py"
      - "scripts/safeparse.py"
      - "scripts/sect233r1.py"
      - "scripts/sitediagrams.py"
      - "scripts/siteguides.py"
      - "scripts/sitemarkup.py"
      - "scripts/siteexports.py"
      - "scripts/siterender.py"
      - "scripts/sitesources.py"
      - "scripts/sitestarlight.py"
      - "scripts/sitewrite.py"
      - "scripts/slot.py"
      - "scripts/slots.py"
      - "scripts/sourceref.py"
      - "scripts/split_pack.py"
      - "scripts/truth.py"
      - "scripts/upstream.py"
      - "scripts/validate_schemas.py"
      - "scripts/validate_site.py"
      - "scripts/validation.py"
      - "scripts/verify.py"
      - "scripts/ziptools.py"
      - "schemas/**"
      - "docs_assets/**"
      - "install/**"
      - "install.py"
      - "database.json"
      - "release.json"
      - "derivable.json"
      # The Starlight project: config, components, styles, lockfile. Its
      # generated folders are gitignored and never trigger anything.
      - "website/**"
      - ".github/workflows/deploy-site.yml"
  workflow_dispatch:

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

concurrency:
  # Pages deployments must run to completion: cancelling one mid-flight
  # leaves the deployment stuck and makes the next runs time out waiting
  # on it. Queued runs collapse to the latest instead.
  group: pages
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7

      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7
        with:
          python-version: "3.12"

      - run: pip install pyyaml "jsonschema[format-nongpl]==4.26.0"

      # Node builds the site only: the scripts stay Python. The engine and
      # its plugins are pinned exactly in website/package.json and resolved
      # from the committed lockfile.
      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1  # v7.1.0
        with:
          node-version: "24"
          cache: npm
          cache-dependency-path: website/package-lock.json

      - run: npm ci --prefix website

      - name: Validate data contracts
        run: python scripts/validate_schemas.py

      # Coverage is resolved against the disk, so a checkout without the
      # release assets and the data caches reports files as missing and the
      # generated README stops matching the committed one.
      - name: Restore large files from release
        run: |
          mkdir -p .cache/large
          gh release download large-files -D .cache/large/ 2>/dev/null || true
          python scripts/restore_large_files.py
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Refresh data directories
        run: python scripts/refresh_data_dirs.py

      - name: Generate site
        run: |
          python scripts/generate_site.py
          python scripts/generate_readme.py --db database.json --platforms-dir platforms
          # starlight-links-validator fails the build on a dead link or anchor.
          npm run build --prefix website
          python scripts/validate_site.py --site-dir website/dist

      # The queries a visitor types must reach the page that answers them,
      # read through the site's own search box, and the home page must stay
      # under its weight budget. A miss blocks the deploy. The browser driver
      # is not a dependency of the build: pinned here, not saved to the
      # lockfile, and it drives the Chrome the runner image ships.
      - name: Search gate
        run: |
          npm install --no-save --prefix website playwright-core@1.58.0
          python website/tools/search_gate.py --site-dir website/dist

      # write_if_changed() compares content with its timestamp line stripped,
      # so a run that only moves the clock leaves the file untouched and this
      # stays a real staleness check rather than a guaranteed failure.
      - name: Require committed README and CONTRIBUTING to be current
        run: git diff --exit-code -- README.md CONTRIBUTING.md

      - name: Setup Pages
        uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d  # v6

      - name: Upload artifact
        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9  # v5
        with:
          path: website/dist/

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