docs.yaml

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

name: Documentation

on:
  # Build-only triggers — exercise the docs pipeline so breakage is
  # caught at PR / merge time, but do NOT publish to GitHub Pages.
  # Deployment is gated on the `release` event below.
  push:
    branches:
      - main
    paths:
      - 'docs/**'
      - 'src/**/*.rs'
      - '.github/workflows/docs.yaml'
  pull_request:
    paths:
      - 'docs/**'
      - 'src/**/*.rs'
      - '.github/workflows/docs.yaml'
  # Deploy trigger — fires when an operator publishes a GitHub Release.
  # The docs site published to Pages is what end users see, so we tie
  # publish cadence to the release cadence: every release ships matching
  # docs, and intermediate main commits don't churn the live site.
  release:
    types: [published]
  workflow_dispatch:

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

# Build runs on every PR / push and can race with itself — cancel
# in-progress to keep CI from queuing redundant builds. Release deploys
# happen at most once per release tag and must NEVER be cancelled by a
# subsequent push (operators rely on the published release deploying);
# the `cancel-in-progress` expression below disables cancellation only
# for the release event.
concurrency:
  group: pages-${{ github.event_name == 'release' && github.event.release.tag_name || github.ref }}
  cancel-in-progress: ${{ github.event_name != 'release' }}

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@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
        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@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.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@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
        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@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
        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

      # Pages setup + artifact upload only happen when the trigger is a
      # release publication. PR / push runs build the site (proving it
      # compiles cleanly) but never produce a deploy artifact.
      - name: Setup Pages
        if: github.event_name == 'release'
        uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0

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

  deploy:
    name: 🚀 Deploy to GitHub Pages
    # Gated on the `release: published` event — a main push or PR build
    # validates the docs but does NOT publish them. The published site
    # tracks release cadence so end users see a stable, versioned doc
    # set rather than every intermediate main commit.
    if: github.event_name == 'release'
    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