docs-check.yml

name: Documentation Check

on:
  pull_request:
    branches: [main]
    paths:
      - 'docs/**'
      - 'README.md'
      - 'CHANGELOG.md'

permissions:
  contents: read

jobs:
  check-docs-updated:
    name: Check docs updated with code changes
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
          fetch-depth: 0

      - name: Get changed files
        id: changed-files
        uses: tj-actions/changed-files@22103cc46bda19c2b464ffe86db46df6922fd323 # v47.0.5
        with:
          files_yaml: |
            src:
              - 'src/**/*.ts'
            docs:
              - 'README.md'
              - 'CHANGELOG.md'
              - 'docs/docs/**/*.md'

      - name: Check if docs were updated with src changes
        if: steps.changed-files.outputs.src_any_changed == 'true'
        run: |
          if [ "${{ steps.changed-files.outputs.docs_any_changed }}" != "true" ]; then
            echo "::warning::Source code was changed but no documentation was updated."
            echo ""
            echo "Please ensure documentation is updated when making code changes:"
            echo "  - README.md (for new features/flags)"
            echo "  - docs/docs/cli/*.md (for CLI changes)"
            echo "  - docs/docs/sources/*.md (for source changes)"
            echo "  - CHANGELOG.md (under [Unreleased])"
            echo ""
            echo "See CONTRIBUTING.md for documentation requirements."
            echo ""
            echo "If this change doesn't require documentation updates, add [skip-docs-check] to your PR title."
          else
            echo "Documentation was updated with source changes."
          fi

      - name: Skip check if marked
        if: contains(github.event.pull_request.title, '[skip-docs-check]')
        run: echo "Documentation check skipped via PR title."

  build-docs:
    name: Build documentation
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6

      - name: Setup pnpm
        uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061 # v4

      - name: Setup Node.js
        uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6
        with:
          node-version: '20'
          cache: 'pnpm'
          cache-dependency-path: docs/pnpm-lock.yaml

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

      - name: Build docs
        working-directory: docs
        run: pnpm build

      - name: Validate SEO/AEO artifacts
        working-directory: docs
        run: pnpm seo:check