deploy.yml

# Deploy multilingual docs to GitHub Pages.
#
# This workflow replaces GitHub's default Jekyll deployment so we can:
#   1. Build the browser WASM bundle from demo.ml via WATCodeGenerator.
#      `multilingual build-wasm-bundle demo.ml` emits:
#        - module.wat        (WebAssembly Text — educational display in docs)
#        - module.wasm       (binary — executed in the browser REPL)
#        - host_shim.js      (JS host import stubs for print_str, print_f64, …)
#        - abi_manifest.json (ABI metadata)
#   2. Copy all bundle artifacts into assets/wasm/.
#   3. Build the Jekyll site.
#   4. Deploy _site/ to GitHub Pages.
#
# The build is purely Python-driven (multilingualprogramming[wasm]).
# No Rust toolchain or wasm-pack is required.
#
# Trigger: every push to main, or manually via workflow_dispatch.

name: Build and deploy docs

on:
  push:
    branches: [main]
  workflow_dispatch:

# Required for the deploy-pages action.
permissions:
  contents: read
  pages:    write
  id-token: write

# Cancel in-progress runs on the same branch so pushes don't queue up.
concurrency:
  group:              pages-${{ github.ref }}
  cancel-in-progress: true

jobs:
  # ── Job 1: Test every executable doc block ────────────────────────────────
  test-blocks:
    name: Test doc code blocks
    runs-on: ubuntu-latest

    steps:
      - name: Checkout docs repo
        uses: actions/checkout@v4

      - name: Checkout multilingual source
        uses: actions/checkout@v4
        with:
          repository: johnsamuelwrites/multilingual
          path:       multilingual-src

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.12'
          cache:          pip
          cache-dependency-path: multilingual-src/pyproject.toml

      - name: Install multilingual with WASM extras
        working-directory: multilingual-src
        run: pip install -e ".[dev,wasm]"

      - name: Install wabt (wat2wasm, wasm-validate)
        run: sudo apt-get install -y wabt

      - name: Install pytest
        run: pip install pytest

      - name: Run code-block tests
        run: pytest _tests/ -v --tb=short

  # ── Job 2: Build WASM ────────────────────────────────────────────────────
  build-wasm:
    name: Build WASM browser bundle
    runs-on: ubuntu-latest
    needs: test-blocks

    steps:
      - name: Checkout docs repo (for demo.ml)
        uses: actions/checkout@v4

      - name: Checkout multilingual source
        uses: actions/checkout@v4
        with:
          repository: johnsamuelwrites/multilingual
          path:       multilingual-src

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.12'
          cache:          pip
          cache-dependency-path: multilingual-src/pyproject.toml

      - name: Install multilingual with WASM extras
        working-directory: multilingual-src
        run: pip install -e ".[dev,wasm]"

      # wabt must be installed before the bundle build so wat2wasm is
      # available to assemble the WAT text → WASM binary.
      - name: Install wabt (wat2wasm, wasm-validate, wasm2wat)
        run: sudo apt-get install -y wabt

      - name: Build browser WASM bundle from demo.ml
        run: |
          # WATCodeGenerator compiles demo.ml → WAT text (module.wat).
          # Additional artifacts: host_shim.js, abi_manifest.json
          mkdir -p wasm-out
          multilingual build-wasm-bundle demo.ml --out-dir wasm-out

      - name: Assemble and validate demo WASM binary
        run: |
          # Assemble the canonical WAT text into a binary.
          # This works whether build-wasm-bundle emits .wasm or not;
          # we always produce the binary from the WAT source of truth.
          wat2wasm wasm-out/module.wat -o wasm-out/module.wasm
          wasm-validate wasm-out/module.wasm

      - name: Stage all WASM artifacts under assets/wasm/
        run: |
          # Collect everything into assets/wasm/ so the artifact layout
          # matches the Jekyll source tree exactly.
          mkdir -p assets/wasm/blocks
          # Rename module.* → multilingual.* and move into assets/wasm/
          mv wasm-out/module.wasm       assets/wasm/multilingual.wasm
          mv wasm-out/module.wat        assets/wasm/multilingual.wat
          mv wasm-out/host_shim.js      assets/wasm/host_shim.js
          mv wasm-out/abi_manifest.json assets/wasm/abi_manifest.json
          # Per-block binaries compiled in the next step land in assets/wasm/blocks/

      - name: Compile per-block WASM binaries
        run: |
          # Each executable code block in the docs gets its own WASM binary,
          # keyed by SHA-256 hash of its content, stored in assets/wasm/blocks/.
          # The browser Run button fetches the per-block binary and executes it,
          # falling back to the demo binary if a block wasn't compiled.
          python _scripts/compile_blocks.py

      - name: Upload WASM artefacts
        uses: actions/upload-artifact@v4
        with:
          name: wasm-pkg
          path: assets/wasm/
          retention-days: 1

  # ── Job 3: Build Jekyll ───────────────────────────────────────────────────
  build-jekyll:
    name: Build Jekyll site
    runs-on: ubuntu-latest
    needs: build-wasm

    steps:
      - name: Checkout docs repo
        uses: actions/checkout@v4

      - name: Download WASM artefacts
        uses: actions/download-artifact@v4
        with:
          name: wasm-pkg
          path: assets/wasm/
        # Downloaded layout (relative to repo root):
        #   assets/wasm/multilingual.wasm, multilingual.wat, …
        #   assets/wasm/blocks/<hash16>.wasm  (one per compiled code block)

      - name: Set up Ruby
        uses: ruby/setup-ruby@v1
        with:
          ruby-version:  '3.3'
          bundler-cache: true   # runs `bundle install` and caches gems

      - name: Configure GitHub Pages
        id:   pages
        uses: actions/configure-pages@v5

      # Jekyll is built with JEKYLL_ENV=production so jekyll-seo-tag,
      # jekyll-sitemap, etc. output canonical URLs correctly.
      - name: Build Jekyll site
        env:
          JEKYLL_ENV: production
        run: bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}"

      - name: Inject block hashes into built HTML
        run: python _scripts/inject_hashes.py

      - name: Upload Pages artefact
        uses: actions/upload-pages-artifact@v3
        with:
          path: _site/

  # ── Job 4: Deploy ─────────────────────────────────────────────────────────
  deploy:
    name: Deploy to GitHub Pages
    runs-on: ubuntu-latest
    needs: build-jekyll

    environment:
      name: github-pages
      url:  ${{ steps.deploy.outputs.page_url }}

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