docs-review.yml

name: Documentation Review

on:
  pull_request:
    paths:
      - 'docs/**'
      - '*.md'
  push:
    branches:
      - main
    paths:
      - 'docs/**'
      - '*.md'
  workflow_dispatch:

jobs:
  review-docs:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.12'

      - name: Install PDM
        run: pip install pdm

      - name: Install dependencies
        run: pdm install

      - name: Build documentation
        run: pdm run docs
        continue-on-error: true

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code

      - name: Review documentation with Claude Code
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          # Create the review prompt
          cat > /tmp/review-prompt.txt << 'PROMPT_EOF'
          Review the ChipFlow documentation for quality, accuracy, and consistency.

          ## Context
          ChipFlow is a platform for designing and building hardware systems (SoCs) using Python and Amaranth HDL.

          ## Review the following:

          1. **Technical Accuracy**
             - Do code examples work with the current API?
             - Are command-line examples correct?
             - Are configuration file examples valid?

          2. **Consistency**
             - Is terminology used consistently?
             - Are code style conventions consistent?

          3. **Flow and Organization**
             - Does the getting-started guide provide a clear path?
             - Do topics build logically on each other?

          4. **Completeness**
             - Are all major features documented?
             - Are there gaps that would confuse users?

          ## Output Format
          Provide findings as:

          ## Summary
          [1-2 sentence assessment]

          ## Issues Found

          ### Critical
          [Issues preventing users from following docs]

          ### Major
          [Significant inaccuracies]

          ### Minor
          [Small improvements]

          ## Recommendations
          [Top 3-5 actionable improvements]

          Focus on docs/source/ and .md files. Report actual issues only.
          PROMPT_EOF

          # Run Claude Code in print mode (non-interactive)
          claude --print "$(cat /tmp/review-prompt.txt)" > review-results.txt 2>&1 || true

          # Show the results
          cat review-results.txt

      - name: Process review results
        id: process-review
        run: |
          if [ -f review-results.txt ] && [ -s review-results.txt ]; then
            # Use heredoc to handle multiline output
            {
              echo 'review<<EOF'
              cat review-results.txt
              echo 'EOF'
            } >> $GITHUB_OUTPUT
          else
            echo "review=Documentation review did not produce output" >> $GITHUB_OUTPUT
          fi

      - name: Comment on PR
        if: github.event_name == 'pull_request'
        uses: actions/github-script@v7
        with:
          script: |
            const review = process.env.REVIEW_CONTENT;

            // Find existing comment from this workflow
            const { data: comments } = await github.rest.issues.listComments({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
            });

            const botComment = comments.find(comment =>
              comment.user.type === 'Bot' &&
              comment.body.includes('## 📚 Documentation Review')
            );

            const body = `## 📚 Documentation Review

            ${review}

            ---
            *This review was automatically generated by Claude Code*`;

            if (botComment) {
              await github.rest.issues.updateComment({
                owner: context.repo.owner,
                repo: context.repo.repo,
                comment_id: botComment.id,
                body: body
              });
            } else {
              await github.rest.issues.createComment({
                owner: context.repo.owner,
                repo: context.repo.repo,
                issue_number: context.issue.number,
                body: body
              });
            }
        env:
          REVIEW_CONTENT: ${{ steps.process-review.outputs.review }}

      - name: Upload review results
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: docs-review-results
          path: review-results.txt
          retention-days: 30