auto-documentation.yml

name: Auto Documentation

on:
  workflow_dispatch:
  workflow_call:

permissions:
  contents: write
  pull-requests: write
  id-token: write

jobs:
  auto-documentation:
    name: Generate Documentation
    runs-on: ubuntu-latest
    timeout-minutes: 15

    steps:
      - name: Checkout PR Branch
        uses: actions/checkout@v4
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          ref: ${{ github.head_ref || github.ref_name }}
          fetch-depth: 0

      - name: Check if last commit was auto-documentation
        id: check-auto-commit
        run: |
          LAST_COMMIT_MSG=$(git log -1 --pretty=format:"%s")
          if [[ "$LAST_COMMIT_MSG" == *"Auto-generate documentation"* ]]; then
            echo "auto-commit=true" >> "$GITHUB_OUTPUT"
            echo "Last commit was auto-documentation - skipping to prevent loops"
          else
            echo "auto-commit=false" >> "$GITHUB_OUTPUT"
            echo "Last commit was not auto-documentation - analyzing code for documentation updates"
          fi

      - name: Get Changed Apex Files
        if: steps.check-auto-commit.outputs.auto-commit == 'false'
        id: changed-files
        run: |
          # Get list of changed .cls files in source and plugins directories
          git diff --name-only origin/main..HEAD | grep -E '\.(cls|trigger)$' > changed_files.txt || touch changed_files.txt

          if [ -s changed_files.txt ]; then
            echo "has-apex-changes=true" >> "$GITHUB_OUTPUT"
            echo "Changed Apex files:"
            cat changed_files.txt
          else
            echo "has-apex-changes=false" >> "$GITHUB_OUTPUT"
            echo "No Apex files changed"
          fi

      - name: Analyze Code Changes with Claude
        if: steps.check-auto-commit.outputs.auto-commit == 'false' && steps.changed-files.outputs.has-apex-changes == 'true'
        uses: anthropics/claude-code-action@beta
        with:
          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
          direct_prompt: |
            I need you to analyze the changed Apex files in this PR and automatically generate/update wiki documentation.

            ## Your Task:
            1. **Analyze each changed .cls and .trigger file** to identify new or modified `global` elements:
               - New `global` classes (including inner types)
               - New `global` methods
               - New `global` properties
               - Modified signatures of existing global elements

            2. **Generate wiki documentation** for any new global elements:
               - Create new wiki files for new global classes following the pattern `The-[ClassName]-Class.md`
               - Add new methods to existing class documentation files in the wiki directory
               - Add new properties to existing class documentation files in the wiki directory
               - Update `wiki/_Sidebar.md` to include new class files in alphabetical order within their appropriate sections

            3. **Follow the existing documentation patterns** in the `wiki/` directory:
               - Use the same markdown structure and formatting as existing files
               - Include method signatures, parameter descriptions, and return types
               - Add code examples where appropriate
               - Maintain consistent cross-references between files using relative links
               - Follow the existing naming conventions exactly

            ## Important Guidelines:
            - Only document `global` elements (ignore private/protected/public without global)
             - Follow the existing wiki file naming conventions exactly (The-[ClassName]-Class.md)
            - Preserve existing content - only add new sections or update existing ones
            - If no new global elements are found, create no files
            - When updating existing files, insert new content in appropriate sections
            - Maintain alphabetical ordering in _Sidebar.md

            ## Expected Output:
            Create or modify files in the `wiki/` directory as needed. I will review these changes as part of the PR.

      - name: Remove Claude Attribution
        if: steps.check-auto-commit.outputs.auto-commit == 'false' && steps.changed-files.outputs.has-apex-changes == 'true'
        run: |
          BRANCH="${{ github.head_ref || github.ref_name }}"
          BASE=$(git rev-parse "origin/${BRANCH}" 2>/dev/null || echo "")
          if [ -z "$BASE" ]; then
            echo "Cannot determine base commit; skipping attribution cleanup"
            exit 0
          fi
          if git log --format="%B" "${BASE}..HEAD" 2>/dev/null | grep -qi "co-authored-by.*claude"; then
            echo "Stripping Claude Co-authored-by trailers from new commits..."
            GIT_SEQUENCE_EDITOR="sed -i 's/^pick /reword /g'" \
            GIT_EDITOR="sed -i '/[Cc]o-[Aa]uthored-[Bb]y.*[Cc]laude/d'" \
            git rebase -i "${BASE}"
            git push origin "HEAD:${BRANCH}" --force
          else
            echo "No Claude attribution found in new commits"
          fi

      - name: Check if Home.md Changed
        if: steps.check-auto-commit.outputs.auto-commit == 'false'
        id: check-home
        run: |
          # Check if wiki/Home.md was modified in the previous documentation step
          if git diff --quiet HEAD -- wiki/Home.md; then
            echo "home-changed=false" >> "$GITHUB_OUTPUT"
            echo "wiki/Home.md was not changed"
          else
            echo "home-changed=true" >> "$GITHUB_OUTPUT"
            echo "wiki/Home.md was changed"
          fi

      - name: Sync Home.md to README.md
        if: steps.check-auto-commit.outputs.auto-commit == 'false' && steps.check-home.outputs.home-changed == 'true'
        run: |
          # Copy wiki/Home.md content to README.md
          if [ -f wiki/Home.md ]; then
            cp wiki/Home.md README.md
            echo "Copied wiki/Home.md to README.md"
          else
            echo "wiki/Home.md not found, skipping sync"
          fi

      - name: Check for Documentation Changes
        if: steps.check-auto-commit.outputs.auto-commit == 'false'
        id: check-docs
        run: |
          if git diff --quiet HEAD -- wiki/ README.md; then
            echo "has-doc-changes=false" >> "$GITHUB_OUTPUT"
            echo "No documentation changes generated"
          else
            echo "has-doc-changes=true" >> "$GITHUB_OUTPUT"
            echo "Documentation changes detected:"
            git diff --name-only HEAD -- wiki/ README.md
          fi

      - name: Commit Documentation Updates
        if: steps.check-auto-commit.outputs.auto-commit == 'false' && steps.check-docs.outputs.has-doc-changes == 'true'
        run: |
          rm -f changed_files.txt
          git config --local user.email "action@github.com"
          git config --local user.name "GitHub Action"
          git add wiki/ README.md
          git commit -m "Auto-generate documentation for code changes

          Generated documentation for new global classes/methods/properties"

          git push origin ${{ github.head_ref || github.ref_name }}