site.yml

name: Site

on:
  push:
    branches: [main]
  pull_request:
  workflow_dispatch:

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

concurrency:
  group: site
  cancel-in-progress: true

jobs:
  build:
    if: ${{ github.server_url == 'https://github.com' }}
    runs-on: ubuntu-latest
    # A wedged step must fail the run, not sit on it. The default is six hours,
    # which is how a hanging browser check burned a deploy instead of reporting.
    timeout-minutes: 35

    steps:
      - uses: actions/checkout@v4

      - name: Checkout SolverForge runtime source
        uses: actions/checkout@v4
        with:
          repository: SolverForge/solverforge
          path: .ci/solverforge-rs
          fetch-depth: 0

      - name: Checkout SolverForge maps source
        uses: actions/checkout@v4
        with:
          repository: SolverForge/solverforge-maps
          path: .ci/solverforge-maps

      - name: Checkout SolverForge UI source
        uses: actions/checkout@v4
        with:
          repository: SolverForge/solverforge-ui
          path: .ci/solverforge-ui

      # The bench docs page describes this revision; the companion-docs gate
      # compares the page with its Makefile, harness, and migrations.
      - name: Checkout documented SolverForge bench revision
        uses: actions/checkout@v4
        with:
          repository: SolverForge/solverforge-bench
          ref: 712a30205590f8aad81ce42bf360a281cd152f0f
          path: .ci/solverforge-bench

      - name: Install Rust 1.95
        run: |
          rustup toolchain install 1.95.0 --profile minimal
          rustup default 1.95.0

      # The maintenance walkthrough and the CLI Getting Started page replay
      # their commands with the published CLI and solve the result, so CI
      # needs the exact release they document (scripts/release_pins.rb).
      - name: Cache the walkthrough toolchain
        uses: actions/cache@v4
        with:
          path: |
            ~/.cargo/registry
            ~/.cargo/git
            ~/.cargo/bin/solverforge
            ~/.cache/walkthrough-target
            ~/.cache/getting-started-target
          key: walkthrough-solverforge-cli-3.9.0-${{ hashFiles('scripts/fixtures/maintenance-walkthrough/**') }}
          restore-keys: walkthrough-solverforge-cli-3.9.0-

      # The Rust library pages compile and run against crates.io solverforge;
      # keep that build between runs.
      - name: Cache the Rust snippet build
        uses: actions/cache@v4
        with:
          path: ~/.cache/rust-snippets-target
          key: rust-snippets-${{ hashFiles('scripts/lib/rust_pages.rb') }}-${{ github.sha }}
          restore-keys: rust-snippets-${{ hashFiles('scripts/lib/rust_pages.rb') }}-

      # The solver-page gate parses and solves every config block with the
      # published solverforge crate pinned in its fixture's Cargo.lock.
      - name: Cache the solver-config fixture build
        uses: actions/cache@v4
        with:
          path: |
            ~/.cargo/registry/index
            ~/.cargo/registry/cache
            ~/.cache/solver-config-target
          key: solver-config-${{ hashFiles('scripts/fixtures/solver-config/Cargo.lock') }}-${{ hashFiles('scripts/fixtures/solver-config/src/**') }}
          restore-keys: solver-config-${{ hashFiles('scripts/fixtures/solver-config/Cargo.lock') }}-

      - name: Install solverforge-cli 3.9.0
        run: |
          if ! solverforge --version 2>/dev/null | grep -q 'CLI version: 3.9.0'; then
            cargo install solverforge-cli --version 3.9.0 --locked --force
          fi
          solverforge --version

      # The Python docs gate installs the published PyPI package into fresh
      # venvs and replays the pages, so CI needs the interpreter they name.
      - uses: actions/setup-python@v5
        with:
          python-version: "3.14"
          cache: pip
          cache-dependency-path: src/docs/solverforge-python/*.md

      # The UI getting-started gate builds the page's crate from crates.io.
      - name: Cache the UI getting-started build
        uses: actions/cache@v4
        with:
          path: ~/.cache/ui-gate-target
          key: ui-gate-${{ hashFiles('src/docs/solverforge-ui/getting-started.md') }}
          restore-keys: ui-gate-


      - uses: ruby/setup-ruby@v1
        with:
          ruby-version: 3.4

      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
          cache-dependency-path: package-lock.json

      - name: Install dependencies
        run: make install

      - name: Install Playwright browsers
        # Chrome carries the H.264/AAC decoders the media checks need; the
        # bundled Chromium cannot load any MP4.
        run: npx playwright install --with-deps chromium chrome

      - name: Run local CI gate
        env:
          SOLVERFORGE_RS_REPO: ${{ github.workspace }}/.ci/solverforge-rs
          SOLVERFORGE_MAPS_REPO: ${{ github.workspace }}/.ci/solverforge-maps
          SOLVERFORGE_UI_REPO: ${{ github.workspace }}/.ci/solverforge-ui
          SOLVERFORGE_BENCH_REPO: ${{ github.workspace }}/.ci/solverforge-bench
          PLAYWRIGHT_CHANNEL: chrome
        # The use-case tutorial replays build two apps each and run their
        # test suites, so they run in the `tutorials` job below instead.
        run: SOLVERFORGE_WALKTHROUGH_TARGET_DIR="$HOME/.cache/walkthrough-target" SOLVERFORGE_GETTING_STARTED_TARGET_DIR="$HOME/.cache/getting-started-target" SOLVERFORGE_SNIPPETS_TARGET_DIR="$HOME/.cache/rust-snippets-target" SOLVER_CONFIG_TARGET_DIR="$HOME/.cache/solver-config-target" SOLVERFORGE_UI_GATE_TARGET_DIR="$HOME/.cache/ui-gate-target" make ci-local TUTORIAL_REPLAYS=

      - name: Configure Pages
        if: github.event_name != 'pull_request'
        uses: actions/configure-pages@v5

      - name: Upload Pages artifact
        if: github.event_name != 'pull_request'
        uses: actions/upload-pages-artifact@v3
        with:
          path: output

  # Each use-case page is replayed the way a reader follows it: the published
  # CLI builds and solves the page's app, the Hugging Face Space it names is
  # cloned, solved, compared with the page, and validated with the page's own
  # commands. See scripts/lib/use_case_tutorial.rb.
  tutorials:
    if: ${{ github.server_url == 'https://github.com' }}
    runs-on: ubuntu-latest
    timeout-minutes: 60
    strategy:
      fail-fast: false
      matrix:
        page: [hospital, lessons, deliveries, fsr]

    steps:
      - uses: actions/checkout@v4

      - name: Install Rust 1.95
        run: |
          rustup toolchain install 1.95.0 --profile minimal --component rustfmt,clippy
          rustup default 1.95.0

      - name: Cache the tutorial toolchain and builds
        uses: actions/cache@v4
        with:
          path: |
            ~/.cargo/registry
            ~/.cargo/git
            ~/.cache/solverforge-cli
            ~/.cache/tutorial-target
            ~/.cache/tutorial-osm
          key: tutorial-${{ matrix.page }}-${{ hashFiles(format('src/docs/getting-started/solverforge-{0}-use-case.md', matrix.page), 'scripts/lib/*.rb') }}
          restore-keys: tutorial-${{ matrix.page }}-

      - uses: ruby/setup-ruby@v1
        with:
          ruby-version: 3.4

      - uses: actions/setup-node@v4
        with:
          node-version: 22

      - name: Replay the ${{ matrix.page }} tutorial
        env:
          # The Space's browser tests use the runner's Chrome instead of
          # downloading Playwright's Chromium.
          PLAYWRIGHT_CHROMIUM_EXECUTABLE: /usr/bin/google-chrome
        run: |
          export TUTORIAL_REPLAY_TARGET_DIR="$HOME/.cache/tutorial-target"
          export TUTORIAL_REPLAY_OSM_CACHE="$HOME/.cache/tutorial-osm"
          # The public Overpass API blocks cloud runners; see use_case_tutorial.rb.
          export TUTORIAL_REPLAY_OVERPASS=0
          make verify-${{ matrix.page }}-tutorial

  deploy:
    if: ${{ github.server_url == 'https://github.com' && github.event_name != 'pull_request' }}
    needs: [build, tutorials]
    runs-on: ubuntu-latest
    timeout-minutes: 10
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4