# jps-ado-pr-utils

![Build](https://github.com/jai-python3/jps-ado-pr-utils/actions/workflows/test.yml/badge.svg)
![Publish to PyPI](https://github.com/jai-python3/jps-ado-pr-utils/actions/workflows/publish-to-pypi.yml/badge.svg)
[![codecov](https://codecov.io/gh/jai-python3/jps-ado-pr-utils/branch/main/graph/badge.svg)](https://codecov.io/gh/jai-python3/jps-ado-pr-utils)

Python utilities for retrieving and managing Azure DevOps pull request metadata with rich CLI output.

## 🚀 Overview

`jps-ado-pr-utils` is a command-line tool that helps you track and manage pull requests across multiple Azure DevOps projects. It provides a clean, color-coded interface to view PRs where you're assigned as a reviewer, helping you prioritize your code review workload.

### Features

- 📋 **Multi-Project Support**: Query PRs across multiple Azure DevOps projects simultaneously
- 🎯 **Smart Filtering**: Filter PRs by your reviewer status (required vs. optional) and PR status (active, completed, abandoned, or all)
- 📊 **Rich CLI Output**: Beautiful, color-coded tables with clear PR metadata
- 🗓️ **Age Sorting**: PRs sorted by creation date (oldest first) to identify review debt
- ✅ **Vote Tracking**: See approval status at a glance (APPROVED, REJECTED, WAITING)
- 🔍 **Status Filtering**: View active, completed (merged), abandoned, or all pull requests
- ⚙️ **Flexible Configuration**: Use command-line arguments or YAML config files
- 🔐 **Secure Authentication**: Personal Access Token (PAT) based authentication

### Example Usage

#### Installation from PyPI

```bash
pip install jps-ado-pr-utils
```

#### Configuration

Create a configuration file at `~/.config/jps-ado-pr-utils/.env`:

```bash
AZDO_PAT=your_personal_access_token_here
AZDO_USER=your.email@example.com
```

#### Basic Usage

List all active (open) PRs where you're a reviewer across specified projects:

```bash
# Using a config file
jps-ado-pr-utils --config-file projects.yaml

# Using command-line project specification
jps-ado-pr-utils --project "Project1,Project2,Project3"
```

#### Status Filtering

```bash
# List all completed/merged PRs
jps-ado-pr-utils --config-file projects.yaml --status completed

# List all abandoned PRs
jps-ado-pr-utils --config-file projects.yaml --status abandoned

# List all PRs regardless of status (active, completed, abandoned)
jps-ado-pr-utils --config-file projects.yaml --status all

# Default behavior (active PRs only)
jps-ado-pr-utils --config-file projects.yaml --status active
# Or simply:
jps-ado-pr-utils --config-file projects.yaml
```

#### Filtering Options

```bash
# Show only PRs where you're a REQUIRED reviewer
jps-ado-pr-utils --config-file projects.yaml --required-only

# Show only PRs where you're assigned as a reviewer (required or optional)
jps-ado-pr-utils --config-file projects.yaml --mine-only

# Combine status and reviewer filters
jps-ado-pr-utils --config-file projects.yaml --status completed --mine-only
```

#### Configuration File Format

Create a YAML file (e.g., `projects.yaml`) with your projects:

```yaml
projects:
  - "Platform Team"
  - "Mobile Apps"
  - "Backend Services"
  - "Infrastructure"
```

#### Sample Output

The tool displays PRs organized by project with the following information:

- PR number
- Creation date (to identify old PRs)
- Author name
- Repository name
- Your reviewer role (REQUIRED/OPTIONAL)
- Current vote status (APPROVED/REJECTED/WAITING)
- PR title
- Direct link to PR

## 📦 Installation

### From PyPI

```bash
pip install jps-ado-pr-utils
```

### From Source

```bash
git clone https://github.com/jai-python3/jps-ado-pr-utils
cd jps-ado-pr-utils
make install
```

## 🛠️ CLI Reference

```
Usage: jps-ado-pr-utils [OPTIONS]

Options:
  --config-file PATH    Path to YAML config file with projects list
  --project TEXT        Comma-separated list of project names
  --status TEXT         Filter by PR status: active, completed, abandoned, or all
                        (default: active)
  --required-only      Show only PRs where you're a required reviewer
  --mine-only          Show only PRs where you're assigned as a reviewer
  --help               Show this message and exit
```

### Status Parameter Values

- `active` (default): Open/active pull requests
- `completed`: Merged/completed pull requests
- `abandoned`: Abandoned pull requests
- `all`: All pull requests regardless of status

## 🔧 Requirements

- Python >= 3.10
- Azure DevOps Personal Access Token with Code (Read) permissions
- Internet connection to access Azure DevOps REST API

## 🧪 Testing

### Running Tests

```bash
# Run all tests
pytest

# Run with verbose output
pytest -v

# Run with coverage report
pytest --cov=src --cov-report=html --cov-report=term

# Run specific test file
pytest tests/test_list_open_prs.py

# Run specific test class
pytest tests/test_list_open_prs.py::TestGetPrsForProject
```

### Test Structure

- `tests/test_constants.py` - Tests for module constants
- `tests/test_list_open_prs.py` - Unit tests for the main module functions
- `tests/test_integration.py` - Integration tests for the CLI application
- `tests/conftest.py` - Pytest configuration and shared fixtures

### Test Coverage

The test suite includes 50+ test cases covering:

#### Unit Tests
- Authentication header generation
- Environment variable loading
- PR retrieval with different status filters (active, completed, abandoned, all)
- Project loading from CLI and config files
- Reviewer role identification (required/optional)
- Reviewer vote tracking
- PR record construction
- Vote text rendering
- CLI argument parsing
- Filter operations (mine-only, required-only)

#### Integration Tests
- Full workflow for active PRs
- Full workflow for completed PRs
- Full workflow for abandoned PRs
- Full workflow for all PRs
- Mine-only and required-only filter integration
- Multiple project handling
- Error handling (authentication failures, missing credentials)
- Output formatting verification
- Empty results handling

## 🧑‍💻 Development

### Setup Development Environment

```bash
# Install with development dependencies
make install

# Run code quality checks
make fix && make format && make lint

# Run tests
make test
```

### Development Commands

```bash
make format    # Format code with black and isort
make lint      # Run flake8, mypy, and other linters
make test      # Run pytest with coverage
make build     # Build distribution packages
```

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📝 Configuration Details

### Environment Variables

The tool reads configuration from `~/.config/jps-ado-pr-utils/.env`:

- `AZDO_PAT`: Your Azure DevOps Personal Access Token
- `AZDO_USER`: Your Azure DevOps username/email

### Generating a Personal Access Token

1. Go to Azure DevOps → User Settings → Personal Access Tokens
2. Create a new token with **Code (Read)** permissions
3. Copy the token and add it to your `.env` file

## 📜 License

MIT License © Jaideep Sundaram

## 🔗 Links

- [GitHub Repository](https://github.com/jai-python3/jps-ado-pr-utils)
- [Issue Tracker](https://github.com/jai-python3/jps-ado-pr-utils/issues)
- [PyPI Package](https://pypi.org/project/jps-ado-pr-utils/)
