regenerate-cmdline-ref.yml

name: Regenerate Command Line Reference
# Security note:
# PRs can come from forks.
# A runner that executes untrusted PR code must not have bot secrets.
# The generate job runs PR code without bot secrets.
# The apply job runs separately and only commits the generated markdown file.
on:
  repository_dispatch:
    types: [regenerate-cmdline-ref-command]
permissions:
  contents: read
jobs:
  generate_cmdline_ref:
    if: >-
      github.repository == 'shader-slang/slang' &&
      github.event.client_payload.github.payload.repository.full_name == 'shader-slang/slang' &&
      github.event.client_payload.pull_request.base.repo.full_name == 'shader-slang/slang'
    runs-on: ubuntu-latest
    steps:
      - name: Checkout target branch
        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
        with:
          repository: shader-slang/slang
          ref: ${{ github.event.client_payload.pull_request.base.ref }}
          submodules: "recursive"
          persist-credentials: false

      - name: Checkout PR branch
        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
        with:
          repository: ${{ github.event.client_payload.pull_request.head.repo.full_name }}
          ref: ${{ github.event.client_payload.pull_request.head.ref }}
          path: pr-branch
          submodules: "recursive"
          persist-credentials: false

      - name: Install dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y libx11-dev

      - name: Setup
        uses: ./.github/actions/common-setup
        with:
          os: linux
          compiler: gcc
          platform: x86_64
          config: release
          build-llvm: false

      - name: Build Slang
        id: build
        run: |
          cd pr-branch
          cmake --preset default --fresh \
            -DSLANG_SLANG_LLVM_FLAVOR=DISABLE \
            -DSLANG_ENABLE_TESTS=OFF \
            -DSLANG_ENABLE_EXAMPLES=OFF \
            -DSLANG_ENABLE_GFX=OFF \
            -DSLANG_ENABLE_SLANGD=OFF \
            -DSLANG_EXCLUDE_DAWN=ON \
            -DSLANG_EXCLUDE_TINT=ON
          cmake --workflow --preset release

      - name: Regenerate Command Line Reference
        id: regen
        run: |
          cd pr-branch
          mkdir -p docs
          ./build/${{ env.cmake_config }}/bin/slangc -help-style markdown -h > docs/command-line-slangc-reference.md 2>&1

      - name: Upload generated reference
        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6
        with:
          name: command-line-reference
          path: pr-branch/docs/command-line-slangc-reference.md
          if-no-files-found: error
          retention-days: 1

  apply_cmdline_ref:
    needs: generate_cmdline_ref
    if: >-
      always() &&
      github.repository == 'shader-slang/slang' &&
      github.event.client_payload.github.payload.repository.full_name == 'shader-slang/slang' &&
      github.event.client_payload.pull_request.base.repo.full_name == 'shader-slang/slang'
    runs-on: ubuntu-latest
    steps:
      - name: Checkout PR branch
        id: checkout-pr
        if: needs.generate_cmdline_ref.result == 'success'
        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
        with:
          repository: ${{ github.event.client_payload.pull_request.head.repo.full_name }}
          ref: ${{ github.event.client_payload.pull_request.head.ref }}
          path: pr-branch
          persist-credentials: false

      - name: Download generated reference
        id: download-doc
        if: needs.generate_cmdline_ref.result == 'success'
        uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7
        with:
          name: command-line-reference
          path: generated-docs

      - name: Apply generated reference
        id: apply-doc
        if: needs.generate_cmdline_ref.result == 'success'
        run: |
          set -euo pipefail
          generated_doc="generated-docs/command-line-slangc-reference.md"
          if [[ ! -f "$generated_doc" || -L "$generated_doc" ]]; then
            echo "Generated reference artifact is missing or invalid" >&2
            exit 1
          fi
          max_size=$((10 * 1024 * 1024))
          actual_size=$(wc -c < "$generated_doc")
          if [[ "$actual_size" -gt "$max_size" ]]; then
            echo "Generated reference artifact is too large" >&2
            exit 1
          fi
          mkdir -p pr-branch/docs
          cp "$generated_doc" pr-branch/docs/command-line-slangc-reference.md

      - name: Configure Git commit signing
        id: git-info
        if: needs.generate_cmdline_ref.result == 'success'
        run: |
          echo "${{ secrets.SLANGBOT_SIGNING_KEY }}" > "${{runner.temp}}"/signing_key
          chmod 600 "${{runner.temp}}"/signing_key
          git -C pr-branch config commit.gpgsign true
          git -C pr-branch config gpg.format ssh
          git -C pr-branch config user.signingkey "${{runner.temp}}"/signing_key
          bot_info=$(curl -s -H "Authorization: Bearer ${{ secrets.SLANGBOT_PAT }}" \
            "https://api.github.com/user")
          echo "bot_identity=$(echo $bot_info | jq --raw-output '.login + " <" + (.id|tostring) + "+" + .login + "@users.noreply.github.com>"')" >> $GITHUB_OUTPUT
          echo "bot_name=$(echo $bot_info | jq --raw-output '.login')" >> $GITHUB_OUTPUT

      - name: Create Pull Request
        id: create-pr
        if: needs.generate_cmdline_ref.result == 'success'
        uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8.1.1
        with:
          token: ${{ secrets.SLANGBOT_PAT }}
          path: pr-branch
          commit-message: "regenerate command line reference"
          title: "Regenerate command line reference for PR #${{ github.event.client_payload.pull_request.number }}"
          body: "Automated command line reference generation for ${{ github.event.client_payload.pull_request.html_url }}"
          committer: ${{ steps.git-info.outputs.bot_identity }}
          author: ${{ steps.git-info.outputs.bot_identity }}
          branch: regenerate-cmdline-ref-${{ github.event.client_payload.pull_request.number }}-${{ github.event.client_payload.pull_request.head.ref }}
          base: ${{ github.event.client_payload.pull_request.head.ref }}
          push-to-fork: ${{ steps.git-info.outputs.bot_name }}/slang
          delete-branch: true

      - name: Remove signing key
        if: always()
        run: rm -f "${{ runner.temp }}/signing_key"

      - name: Comment on PR
        uses: peter-evans/create-or-update-comment@e8674b075228eee787fea43ef493e45ece1004c9 # v5.0.0
        if: always()
        with:
          token: ${{ secrets.SLANGBOT_PAT }}
          repository: shader-slang/slang
          issue-number: ${{ github.event.client_payload.pull_request.number }}
          body: |
            ${{
              needs.generate_cmdline_ref.result != 'success'
              && format('❌ Command line reference generation failed. Please check the [workflow run](https://github.com/{0}/actions/runs/{1})', github.repository, github.run_id)
              || (steps.create-pr.conclusion != 'success'
                  && format('❌ Failed to create regenerate command line reference pull request. Please check the [workflow run](https://github.com/{0}/actions/runs/{1})', github.repository, github.run_id)
                  || format('🌈 Regenerated command line reference, please merge the changes from [this PR]({0})', steps.create-pr.outputs.pull-request-url))
            }}

      - name: Add reaction
        if: needs.generate_cmdline_ref.result == 'success' && steps.create-pr.conclusion == 'success'
        uses: peter-evans/create-or-update-comment@e8674b075228eee787fea43ef493e45ece1004c9 # v5.0.0
        with:
          token: ${{ secrets.SLANGBOT_PAT }}
          repository: shader-slang/slang
          comment-id: ${{ github.event.client_payload.github.payload.comment.id }}
          reactions-edit-mode: replace
          reactions: hooray