architecture-review workflow (stevezau/media_preview_generator)

name: architecture-review
 
# OPTIONAL fallback for PRs from contributors / forks that don't go
# through Claude Code locally. Runs the same audit prompt that the
# ``.claude/agents/architecture-review.md`` skill applies before every
# commit the maintainer creates via Claude Code.
#
# THE PRIMARY PATH is the Claude Code skill - it runs as part of the
# maintainer's existing subscription, no per-push API charge. The
# maintainer's own pushes are already audited locally before they
# land, so this workflow only fires on PRs (where outside contributors
# can't have run the local agent) and manual dispatch.
#
# Workflow no-ops cleanly when ANTHROPIC_API_KEY isn't set, so the
# default state (no key configured) costs $0 and runs nothing.
#
# Cost expectation when the key IS set: ~$0.05 per PR audit at default
# Sonnet 4.6 pricing with the 200KB diff cap. Hard spending limits
# can be set in Anthropic console → Plans & Billing → Spend limit.
#
# Required secrets (only when this workflow is desired):
#   ANTHROPIC_API_KEY - Claude API key. Without it the workflow
#                       silently skips (no failure, no comments).
 
on:
  pull_request:
    branches: [dev, main]
    paths:
      - 'media_preview_generator/**'
      - 'tests/**'
      - 'pyproject.toml'
  workflow_dispatch:
 
permissions:
  contents: read
  pull-requests: write   # to comment audit findings on the PR
 
concurrency:
  group: arch-review-${{ github.ref }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
 
jobs:
  audit:
    timeout-minutes: 30
    name: Architecture review (Claude agent)
    runs-on: latchkey-small
    # Skip cleanly when the API key isn't configured (forks, etc.). The
    # workflow doesn't fail; it just doesn't run the audit.
    if: ${{ github.repository_owner == 'stevezau' }}
    steps:
      - name: Check out
        uses: actions/checkout@v4
        with:
          # Need the merge-base for diff context.
          fetch-depth: 0
 
      - name: Skip if API key missing
        id: gate
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          if [ -z "${ANTHROPIC_API_KEY}" ]; then
            echo "ANTHROPIC_API_KEY not set - skipping architecture review."
            echo "skip=true" >> "$GITHUB_OUTPUT"
          else
            echo "skip=false" >> "$GITHUB_OUTPUT"
          fi
 
      - name: Compute diff scope
        if: steps.gate.outputs.skip != 'true'
        id: diff
        run: |
          # PR: diff against the base. workflow_dispatch (the only other
          # reachable path now that ``push:`` is gone): ``github.event.before``
          # is empty, so fall back to HEAD~1 - audits just the latest
          # commit, which is the natural manual-trigger expectation.
          if [ "${{ github.event_name }}" = "pull_request" ]; then
            BASE="${{ github.event.pull_request.base.sha }}"
          else
            BASE="${{ github.event.before }}"
            if [ -z "$BASE" ] || [ "$BASE" = "0000000000000000000000000000000000000000" ]; then
              BASE="HEAD~1"
            fi
          fi
          # Concise list of changed Python files for the agent prompt.
          CHANGED=$(git diff --name-only "${BASE}" HEAD -- 'media_preview_generator/**.py' 'tests/**.py' || true)
          {
            echo "base=${BASE}"
            echo "changed_files<<EOF"
            echo "${CHANGED}"
            echo "EOF"
          } >> "$GITHUB_OUTPUT"
 
      - name: Set up Python
        if: steps.gate.outputs.skip != 'true'
        uses: actions/setup-python@v5
        with:
          cache: 'pip'
          python-version: "3.12"
 
      - name: Install Anthropic SDK
        if: steps.gate.outputs.skip != 'true'
        run: pip install --quiet "anthropic>=0.40"
 
      - name: Run audit
        if: steps.gate.outputs.skip != 'true' && steps.diff.outputs.changed_files != ''
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          BASE_SHA: ${{ steps.diff.outputs.base }}
          CHANGED_FILES: ${{ steps.diff.outputs.changed_files }}
        run: python .github/scripts/run_architecture_review.py | tee audit-report.md
 
      - name: Upload report
        if: steps.gate.outputs.skip != 'true' && steps.diff.outputs.changed_files != ''
        uses: actions/upload-artifact@v4
        with:
          name: architecture-review-report
          path: audit-report.md
          if-no-files-found: ignore
 
      - name: Post PR comment
        if: >-
          steps.gate.outputs.skip != 'true'
          && steps.diff.outputs.changed_files != ''
          && github.event_name == 'pull_request'
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            if (!fs.existsSync('audit-report.md')) return;
            const body = "## Architecture review (Claude agent)\n\n" +
                         fs.readFileSync('audit-report.md', 'utf8');
            // Replace any prior bot-authored review comment so PRs
            // don't accumulate stale audits.
            const { owner, repo } = context.repo;
            const issue_number = context.issue.number;
            const existing = await github.rest.issues.listComments({ owner, repo, issue_number });
            const prior = existing.data.find(c =>
              c.user.type === 'Bot' && c.body.startsWith("## Architecture review (Claude agent)")
            );
            if (prior) {
              await github.rest.issues.updateComment({ owner, repo, comment_id: prior.id, body });
            } else {
              await github.rest.issues.createComment({ owner, repo, issue_number, body });
            }