docs.yml

# Build + deploy the Astro Starlight documentation site under `docs/`
# to GitHub Pages.
#
# Strategy: build + deploy on pushes to `main`.  `main` only moves when a
# release is cut (see AGENTS.md → Release strategy), so the published docs
# still track released versions — without the `release: [published]`
# trigger, whose runs execute on the TAG ref and are rejected by the
# `github-pages` environment protection rules (only `main` may deploy;
# this is how the v0.11.0 docs deploy failed).  Not built on develop
# pushes/PRs (the build is slow).  Build output is never committed; Pages
# consumes the workflow artifact directly via `actions/deploy-pages`.
#
# **Prerequisite — manual one-time setup**:
#   Settings → Pages → Source: GitHub Actions
# (Without that, the deploy step fails with "Pages site not found".)
#
# **Permissions**: declared per job, never at workflow level (#621).
# `deploy` needs `pages: write` + `id-token: write` to publish the
# artifact via OIDC; `build` needs neither.  Granted once at the top,
# both scopes would also be minted for the job that installs the whole
# docs dependency tree and drives headless Chromium — the job most
# likely to execute someone else's code — even though its only Pages
# step, `actions/upload-pages-artifact`, authenticates with the
# runtime token instead.  A per-job block keeps the deploy credential
# in the job that does nothing but deploy.
name: docs

on:
  # Fire on pushes to `main` — which happen only at release time — so the
  # docs deploy in lockstep with the npm publish and run on a ref the
  # `github-pages` environment protection accepts.  Docs are deliberately
  # NOT built on `develop` pushes/PRs — the build is slow (TypeDoc +
  # Astro + headless-Chromium Mermaid SSR).  Use workflow_dispatch for an
  # out-of-band rebuild.
  push:
    branches: [main]
  workflow_dispatch:

# Avoid in-flight workflow conflicts: cancel any older run on the same
# branch if a new push lands.  Pages itself only accepts one deploy
# at a time anyway.
concurrency:
  group: "pages-${{ github.ref }}"
  cancel-in-progress: false

jobs:
  build:
    name: Build
    runs-on: ubuntu-latest
    # Reads the repository and uploads an artifact — nothing else.  The
    # upload action uses the Actions runtime token, not `GITHUB_TOKEN`,
    # so it needs no Pages scope of its own.
    permissions:
      contents: read
    steps:
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          # Starlight's `lastUpdated` feature reads Git history to show
          # the per-page last-modified date.  Full history (`0`) lets
          # it work; shallow checkout makes every page report "now".
          fetch-depth: 0

      # `bun install` is fast and reads `docs/bun.lock`, but `bun run build`
      # ultimately invokes `astro build` whose shebang spawns Node — so the
      # system Node has to satisfy Astro's minimum (>= 22.12 for Astro 7).
      # We install the repo's `engines` floor.
      - name: Setup Node.js
        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
        with:
          node-version: '24'

      - name: Setup Bun
        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
        with:
          bun-version: latest

      # TypeDoc compiles `../src/` to extract JSDoc — but `src/` imports
      # framework peer-deps (`ts-pattern`, `@types/node`, etc.) that live
      # under the **repo root** `node_modules/`, not under `docs/`.  We
      # therefore install root deps first, then the docs-specific deps.
      # Without this, TypeDoc errors out with TS2307 ("cannot find
      # module 'ts-pattern'") + TS2503 ("cannot find namespace
      # 'NodeJS'") on every source file.
      #
      # Both installs are `--frozen-lockfile`: this workflow used to install
      # whatever `package.json` resolved to, so a lockfile that had drifted from
      # its manifest (Dependabot never regenerates `bun.lock`) built green here
      # against a dependency set nobody had recorded — until a bump resolved to
      # something that did not work and the release docs deploy broke (#473).
      - name: Install root dependencies (for TypeDoc to resolve src/ imports)
        run: bun install --frozen-lockfile

      - name: Install docs dependencies
        working-directory: docs
        run: bun install --frozen-lockfile

      # rehype-mermaid renders ```mermaid``` blocks at build time by
      # driving headless Chromium via Playwright.  The npm package
      # ships only the JS bindings; the actual browser binary has to
      # be fetched separately.  `--with-deps` pulls the Linux system
      # libs Chromium needs on the GH Actions Ubuntu runner.
      - name: Install Playwright browsers (for Mermaid SSR)
        working-directory: docs
        run: bunx playwright install --with-deps chromium

      - name: Build site (includes TypeDoc API generation)
        working-directory: docs
        run: bun run build

      - name: Upload Pages artifact
        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
        with:
          path: docs/dist

  deploy:
    name: Deploy to GitHub Pages
    needs: build
    runs-on: ubuntu-latest
    # The two scopes `actions/deploy-pages` documents as its minimum, and
    # they live here rather than at workflow level so only this job — one
    # step, no checkout, no dependencies — can mint them.  `contents: read`
    # is deliberately absent: this job never reads the repository.
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy
        id: deployment
        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0