docusaurus-deploy.yml

# GitHub Actions workflow for building and deploying Docusaurus site to GitHub Pages
name: Deploy Documentation to GitHub Pages

on:
  # Runs on pushes targeting the default branch
  push:
    branches: ["main", "dev"]
    paths:
      - 'docs/**'
      - 'prompts/**'
      - 'llms.txt'
      - 'CHANGELOG.md'
      - '.github/workflows/docusaurus-deploy.yml'
      # Rebuild WASM when Go source changes
      - 'internal/**'
      - 'cmd/**'
      - 'go.mod'
      - 'go.sum'
      # Web assets (REPL component, etc.)
      - 'web/**'

  # PRs build (but don't deploy) — gates dependency bumps that would break docs.
  pull_request:
    branches: ["dev", "main"]
    paths:
      - 'docs/**'
      - 'prompts/**'
      - 'llms.txt'
      - 'CHANGELOG.md'
      - '.github/workflows/docusaurus-deploy.yml'
      - 'internal/**'
      - 'cmd/**'
      - 'go.mod'
      - 'go.sum'
      - 'web/**'

  # Rebuild daily to pick up newly published packages in the registry
  schedule:
    - cron: '0 6 * * *'  # 06:00 UTC daily

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  # Build job
  build:
    runs-on: ubuntu-latest
    # Run even if commit has [skip ci] when it's from docs automation
    if: ${{ !contains(github.event.head_commit.message, '[skip ci]') || github.actor == 'github-actions[bot]' }}
    steps:
      - name: Checkout
        uses: actions/checkout@v6
        with:
          fetch-depth: 0  # Fetch all history and tags for version generation

      - name: Setup Node.js
        uses: actions/setup-node@v6
        with:
          node-version: '20'
          cache: 'npm'
          cache-dependency-path: './docs/package-lock.json'

      - name: Setup Go
        uses: actions/setup-go@v6
        with:
          go-version: '1.25.10'

      - name: Install jq for stats generation
        run: sudo apt-get update && sudo apt-get install -y jq

      - name: Build WASM binary
        run: make build-wasm

      # Native binary is needed by verify_examples.go (invoked transitively
      # by `make update-readme` below). Without this, the examples page
      # would ship with whatever examples.mdx was last committed.
      - name: Build native ailang binary
        run: make build

      - name: Copy static assets
        run: |
          mkdir -p docs/static/js docs/static/wasm
          cp llms.txt docs/static/
          cp bin/ailang.wasm docs/static/wasm/
          # Download wasm_exec.js from Go repository matching the build version
          GO_VERSION=$(go env GOVERSION)
          curl -sL -o docs/static/wasm/wasm_exec.js "https://raw.githubusercontent.com/golang/go/${GO_VERSION}/misc/wasm/wasm_exec.js"
          cp web/ailang-repl.js docs/static/js/
          cp web/AilangRepl.jsx docs/src/components/

      - name: Install dependencies
        run: make docs-install

      - name: Generate version constants
        run: bash docs/scripts/generate-version-constants.sh

      - name: Generate codebase statistics
        run: |
          # Use latest git tag for version (handles tags on other branches)
          export AILANG_VERSION=$(git tag --sort=-v:refname | head -1)
          bash tools/generate_codebase_stats.sh

      # Regenerate docs/docs/examples.mdx (the examples-status page) and
      # docs/static/badges/examples.json (consumed by a shields.io endpoint
      # badge in README.md). Runs ~ every example once; tolerable inside the
      # docs build since WASM already dominates wall time.
      #
      # We don't `git commit` anything here — the regenerated files are
      # consumed by `make docs-build` below and baked into the Pages artifact.
      # README.md in the dev tree stays static; the badge it points at is
      # the JSON we publish to Pages.
      - name: Regenerate examples status page + badge JSON
        run: |
          # Produce examples_report.json from the freshly-built ailang binary.
          # Intentionally does NOT call `make update-readme` in full: that
          # target also runs update_readme.go, which would clobber the
          # shields.io endpoint badge with a hardcoded one.
          go run ./scripts/verify_examples.go --json > examples_report.json || true

          # Feed the report into the examples-status page (baked into the
          # Docusaurus build; never committed).
          if [ -f examples_report.json ]; then
            go run ./scripts/update_docs_examples.go
          fi

          # Emit the JSON consumed by the shields.io endpoint badge in
          # README.md. Hosted under /badges/ on the docs site.
          mkdir -p docs/static/badges
          if [ -f examples_report.json ]; then
            jq '{
              schemaVersion: 1,
              label: "examples",
              message: "\(.passed) passing",
              color: (
                if .failed == 0 then "brightgreen"
                elif (.passed / .total_examples * 100) >= 80 then "green"
                elif (.passed / .total_examples * 100) >= 60 then "orange"
                else "red"
                end
              )
            }' examples_report.json > docs/static/badges/examples.json
            echo "Badge JSON:"
            cat docs/static/badges/examples.json
          else
            echo "::warning::examples_report.json not produced; badge not refreshed"
          fi

      - name: Sync teaching prompts
        run: bash docs/scripts/sync-prompts.sh

      - name: Sync package registry data
        run: bash docs/scripts/sync-registry.sh
        continue-on-error: true  # Build proceeds even if registry unavailable

      - name: Build Docusaurus site
        run: make docs-build

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v5
        with:
          path: ./docs/build

  # Deployment job
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/dev'
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v5