PR Review Order Tool

Analyzes dependencies between changed files in a Pull Request and generates an optimal review order.

Key Features

• Zero cloning - Analyzes GitHub PRs using API only (no disk space used)
• Smart dependency analysis - Detects imports, symbol usage, and test relationships
• Intelligent ordering - Topological sort with file type prioritization
• Monorepo support - Filter by subdirectory with --subdir

Installation

cd pr-review-order
make install

# Add to PATH (add to ~/.bashrc or ~/.zshrc)
export PATH="$HOME/bin/pr-review-tool:$PATH"
source ~/.bashrc

Requirements

• Python 3.10+
• GitHub CLI (gh) for PR analysis

# Install GitHub CLI
brew install gh  # macOS
sudo apt install gh  # Linux

# Authenticate (one-time)
gh auth login

Usage

Analyze GitHub PR

# Full URL
pr-review-order https://github.com/owner/repo/pull/123

# Short format
pr-review-order owner/repo#123

# Just number (uses current repo's remote)
cd /path/to/your/repo
pr-review-order 123
# Automatically detects: owner/repo#123

# Monorepo subdirectory
pr-review-order 123 --subdir packages/backend

How pr-review-order 123 works:

1. Runs git remote get-url origin in current directory
2. Extracts owner/repo from the URL
3. Fetches PR #123 from that repo
4. Uses GitHub API (no cloning!)

Output Formats

# Compact output (default)
pr-review-order 501

# Show detailed reasoning
pr-review-order 501 --details

# Markdown for PR description
pr-review-order 501 --format markdown

Example Output

Default (compact)

================================================================================
PR REVIEW ORDER
================================================================================

1. src/models/user.py
2. src/services/auth.py
3. tests/test_auth.py

================================================================================
Total files to review: 3
================================================================================

With --details

================================================================================
PR REVIEW ORDER
================================================================================

1. src/models/user.py
   📦 Model
   Why review at this position:
   • Root file with no dependencies within this change set
   • Used by 2 other file(s) in this change

2. src/services/auth.py
   ⚙️ Core
   Why review at this position:
   • Depends on 1 level(s) of other files
   • File type: core
   • Depends on: user.py (imports User, UserRole)

3. tests/test_auth.py
   🧪 Test
   Why review at this position:
   • Depends on 2 level(s) of other files
   • File type: test
   • Tests: auth.py
   • Review after understanding the code it tests

================================================================================
Total files to review: 3
================================================================================

Multiple dependency groups

When a PR has independent groups of files with no cross-dependencies, they are shown separately:

================================================================================
PR REVIEW ORDER
================================================================================

Group 1

1. src/models/user.py
2. src/services/auth.py
3. tests/test_auth.py

Group 2

4. src/utils/cache.py
5. src/services/session.py

================================================================================
Total files to review: 5
================================================================================

Monorepo Support

Use the --subdir flag to filter analysis to a specific subdirectory:

# Structure:
# /repo/
# ├── packages/backend/
# └── packages/frontend/

# Analyze only backend changes in the PR
pr-review-order 501 --subdir packages/backend
# ✓ Only analyzes packages/backend/**
# ✗ Excludes packages/frontend/**

Development

Make Commands

make help              # Show all commands
make install           # Install globally
make update            # Update installed version
make test              # Run all tests (45 tests)
make test-unit         # Unit tests only
make test-integration  # Integration tests only
make clean             # Clean cache files

Running Tests

# All tests
pytest tests/

# Unit tests (fast)
pytest tests/unit/

# Integration tests
pytest tests/integration/

How It Works

1. Fetch PR metadata - Uses gh CLI to get branches and commit refs
2. Get changed files - Fetches file list via GitHub API
3. Download file contents - Fetches each file via API
4. Parse dependencies - Python AST parsing
5. Generate order - Topological sort with priority ranking

Architecture

pr_review_tool/
├── analyzers/
│   └── github_python_analyzer.py   # GitHub API-based analysis
├── models/              # Dependency, FileNode, ReviewOrder
├── graph/               # Topological sort algorithm
├── formatters/          # Console, Markdown output
└── utils/
    ├── git_helper.py    # Git operations
    └── github_api.py    # GitHub API calls

Troubleshooting

"Could not fetch PR details"

# Install/authenticate GitHub CLI
gh auth login
gh auth status

"No changed files found"

• Verify PR has Python files on GitHub
• Check subdirectory filter: --subdir packages/backend
• Ensure the PR is accessible with your GitHub authentication

Monorepo picks up wrong files

Use the --subdir flag to filter to a specific directory:

pr-review-order 501 --subdir packages/backend

Future Enhancements

• JavaScript/TypeScript support
• C# support
• JSON/HTML output formats
• GitLab support
• Cycle detection warnings

License

MIT License

---