SwiftLint/.github/workflows/docs.yml

name: Documentation

on:
  push:
    branches: [main]
  pull_request:

jobs:
  create-docs:
    name: Create
    runs-on: ubuntu-24.04
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
        with:
          persist-credentials: false
      - uses: ruby/setup-ruby@ab177d40ee5483edb974554986f56b33477e21d0 # v1.265.0
        with:
          bundler-cache: true
      - name: Build SwiftLint and SourceKitten
        uses: ./.github/actions/bazel-linux-build
        with:
          target: "//:swiftlint @SourceKittenFramework//:sourcekitten"
        env:
          CI_BAZELRC_FILE_CONTENT: ${{ secrets.CI_BAZELRC_FILE_CONTENT }}
      - name: Get Swift version
        id: swift_version
        run: echo "version=$(swift --version | grep '[5-9]\.[0-9]\+\(\.[0-9]\)\?' -o | head -1)" >> "$GITHUB_OUTPUT"
      - uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
        with:
          key: ${{ runner.os }}-spm-${{ steps.swift_version.outputs.version }}-${{ hashFiles('Package.resolved', 'Package.swift') }}
          restore-keys: ${{ runner.os }}-spm-${{ steps.swift_version.outputs.version }}-
          path: .build
      - name: Generate documentation
        run: |
          export PATH="/usr/share/swift/usr/bin:$PATH"
          make docs_linux
      - name: Process documentation violations
        run: |
          if [ -f "docs/undocumented.json" ]; then
            violation_count=$(ruby -rjson -e "puts JSON.parse(File.read('docs/undocumented.json'))['warnings'].length")

            if [ "$violation_count" -gt 0 ]; then
              echo "⚠️ Found $violation_count documentation violations"

              # Create GitHub annotations for each violation
              ruby -rjson -e "
                data = JSON.parse(File.read('docs/undocumented.json'))
                data['warnings'].each do |warning|
                  # Convert absolute path to relative path for the annotation
                  file_path = warning['file'].gsub('/home/runner/work/SwiftLint/SwiftLint/', '')
                  puts \"::error file=#{file_path},line=#{warning['line']}::Undocumented #{warning['symbol_kind'].split('.').last}: #{warning['symbol']}\"
                end
              "

              exit 1
            else
              echo "✅ No documentation violations found"
            fi
          else
            echo "❌ undocumented.json file not found"
          fi
      - name: Upload documentation
        if: github.event_name == 'push'
        uses: actions/upload-pages-artifact@v4
        with:
          path: docs

  deploy-docs:
    name: Deploy
    runs-on: ubuntu-24.04
    needs: create-docs
    if: github.event_name == 'push'
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy documentation
        id: deployment
        uses: actions/deploy-pages@v4