docs.yaml

# Copyright (c) 2025 Erick Bourgeois, firestoned
# SPDX-License-Identifier: Apache-2.0

name: Documentation

on:
  push:
    branches:
      - main
    paths:
      - 'docs/**'
      - 'src/**/*.rs'
      - '.github/workflows/docs.yaml'
  pull_request:
    paths:
      - 'docs/**'
      - 'src/**/*.rs'
      - '.github/workflows/docs.yaml'
  workflow_dispatch:

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

# Allow one concurrent deployment; cancel any in-progress run on the same
# branch so a rapid series of pushes never leaves a stale deploy running.
concurrency:
  group: "pages"
  cancel-in-progress: true

env:
  CARGO_TERM_COLOR: always
  RUST_BACKTRACE: 1
  # Override the cross-compilation linkers set in .cargo/config.toml.
  # On Linux CI runners the native target IS x86_64-unknown-linux-gnu so
  # cargo picks up the macOS cross-compiler setting — which isn't installed.
  CARGO_TARGET_X86_64_UNKNOWN_LINUX_GNU_LINKER: cc
  CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_LINKER: cc

jobs:
  # Validate the CALM architecture document before building the docs site.
  # Uses the reusable CALM workflow (see .github/workflows/CALM.md).
  # A broken architecture means broken diagrams downstream, so this is a
  # hard gate on every docs build.
  calm-validate:
    name: ✅ Validate CALM architecture
    uses: ./.github/workflows/calm.yaml
    with:
      command: validate
      architecture: docs/architecture/calm/architecture.json
      format: pretty
      verbose: true

  # Render one Mermaid flowchart per CALM flow into docs/src/architecture/.
  # The rendered markdown is uploaded as an artifact and consumed by the
  # build job below. The output directory is gitignored — the file only
  # exists at build time.
  calm-diagrams:
    name: 🧱 Render CALM Mermaid diagrams
    uses: ./.github/workflows/calm.yaml
    with:
      command: template
      architecture: docs/architecture/calm/architecture.json
      template-dir: docs/architecture/calm/templates/mermaid
      output: docs/src/architecture
      clear-output-directory: true
      verbose: true
      upload-artifact: true
      artifact-name: calm-mermaid
      artifact-retention-days: 7

  build:
    name: 📚 Build Documentation
    needs: [calm-validate, calm-diagrams]
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
          fetch-depth: 0  # Full history for git-revision-date-localized plugin

      - name: Download rendered CALM diagrams
        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
        with:
          name: calm-mermaid
          path: docs/src/architecture

      - name: Strip .hbs suffix from rendered files
        run: |
          set -euo pipefail
          shopt -s nullglob
          for f in docs/src/architecture/*.hbs; do
            mv "$f" "${f%.hbs}"
          done
          ls -la docs/src/architecture

      - name: Install Rust toolchain
        uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable (moving ref — re-pin quarterly)

      - name: Set up Python
        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
        with:
          python-version: '3.11'

      - name: Install Poetry
        env:
          # Pinned for reproducibility; bump alongside docs/pyproject.toml.
          POETRY_VERSION: "1.8.4"
        # pip install (vs curl | python3) because the curl-pipe pattern trips
        # Scorecard's Pinned-Dependencies downloadThenRun rule; pip uses
        # PyPI's per-wheel sha256 from the Python package index.
        run: |
          python3 -m pip install --user "poetry==${POETRY_VERSION}"
          echo "$HOME/.local/bin" >> "$GITHUB_PATH"

      - name: Configure Poetry
        run: |
          cd docs
          poetry config virtualenvs.in-project true

      - name: Cache Poetry dependencies
        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
        with:
          path: docs/.venv
          key: ${{ runner.os }}-poetry-${{ hashFiles('docs/pyproject.toml') }}
          restore-keys: |
            ${{ runner.os }}-poetry-

      - name: Install documentation dependencies
        run: |
          cd docs
          poetry install --no-interaction --no-ansi

      - name: Cache cargo build
        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
        with:
          path: |
            ~/.cargo/registry
            ~/.cargo/git
            target
          key: ${{ runner.os }}-cargo-docs-${{ hashFiles('**/Cargo.lock') }}
          restore-keys: |
            ${{ runner.os }}-cargo-docs-

      - name: Build documentation
        # CALM diagrams were rendered by the calm-diagrams job and downloaded
        # above, so skip the local re-render via the Makefile.
        env:
          SKIP_CALM_DIAGRAMS: "1"
        run: make docs

      - name: Check for broken links
        if: github.event_name == 'pull_request'
        continue-on-error: true
        env:
          # Pinned for reproducibility; bump periodically.
          LINKINATOR_VERSION: "6.1.2"
        run: |
          npm install -g "linkinator@${LINKINATOR_VERSION}"
          linkinator docs/site/ --recurse --skip "rustdoc/.*" --verbosity error

      - name: Setup Pages
        if: github.ref == 'refs/heads/main'
        uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0

      - name: Upload Pages artifact
        if: github.ref == 'refs/heads/main'
        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
        with:
          path: docs/site

  deploy:
    name: 🚀 Deploy to GitHub Pages
    if: github.ref == 'refs/heads/main'
    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@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0