Metadata-Version: 2.4
Name: jps-ado-pr-utils
Version: 1.3.0
Summary: Python utils for retrieving pull-request metadata.
Author-email: Jaideep Sundaram <jai.python3@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/jai-python3/jps-ado-pr-utils
Project-URL: Repository, https://github.com/jai-python3/jps-ado-pr-utils
Project-URL: Issues, https://github.com/jai-python3/jps-ado-pr-utils/issues
Keywords: Azure DevOps,Azure,pull-request,automation
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.12.3
Requires-Dist: requests>=2.31.0
Requires-Dist: PyYAML>=6.0
Requires-Dist: python-dotenv>=1.0.1
Requires-Dist: rich>=13.7.0
Provides-Extra: dev
Requires-Dist: flake8>=7.0.0; extra == "dev"
Requires-Dist: black>=24.0.0; extra == "dev"
Requires-Dist: build>=1.2.1; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
Requires-Dist: isort>=5.13.0; extra == "dev"
Requires-Dist: codecov>=2.1.13; extra == "dev"
Requires-Dist: autoflake>=2.3.1; extra == "dev"
Requires-Dist: pre-commit>=3.8.0; extra == "dev"
Requires-Dist: bandit>=1.7.9; extra == "dev"
Requires-Dist: vulture>=2.11; extra == "dev"
Requires-Dist: flynt>=1.0.1; extra == "dev"
Requires-Dist: pydocstyle>=6.3.0; extra == "dev"
Requires-Dist: darglint>=1.8.1; extra == "dev"
Requires-Dist: mypy>=1.12.1; extra == "dev"
Requires-Dist: bump-my-version>=1.0.1; extra == "dev"
Requires-Dist: git-changelog>=2.7.0; extra == "dev"
Dynamic: license-file

# 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.

**Azure DevOps Terminology:**
- **Organization**: Your Azure DevOps organization (e.g., `mycompany`)
- **Project**: Top-level container within the organization (e.g., `Engineering Team`)
- **Repository**: Git repository within a project (e.g., `backend-api`)

This tool queries Azure DevOps **projects** to retrieve PRs, and can optionally filter by specific **repositories**.

### 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 with Azure DevOps project name
jps-ado-pr-utils --project "Engineering Team"

# Filter by specific repositories within a project
jps-ado-pr-utils --project "Engineering Team" --repos "backend-api,frontend-app"
```

#### 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

# Filter by specific repositories
jps-ado-pr-utils --project "Engineering Team" --repos "backend-api,frontend-app,mobile-app"

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

# Filter by repositories and reviewer status
jps-ado-pr-utils --project "Engineering Team" --repos "backend-api" --mine-only
```

#### Configuration File Format

Create a YAML file (e.g., `projects.yaml`) with your Azure DevOps project and optional repository filters:

```yaml
# Specify the Azure DevOps project (required, single value)
project: "Engineering Team"

# Optional: Filter by specific repositories within the project
repositories:
  - "backend-api"
  - "frontend-app"
  - "mobile-app"
```

**Example configs:**

```yaml
# Config 1: All repositories in the project
project: "Engineering Team"
```

```yaml
# Config 2: Only specific repositories
project: "Engineering Team"
repositories:
  - "backend-api"
  - "frontend-app"
```

**Note:** 
- The `--repos` CLI parameter takes precedence over the `repositories` list in the config file
- You can combine config and CLI: config file specifies the project, `--repos` filters repositories

#### 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        Azure DevOps project name (e.g., 'Engineering Team')
  --repos TEXT          Comma-separated list of repository names to filter
  --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
  --outdir PATH        Output directory for logs
                        (default: /tmp/[user]/jps-ado-pr-utils/[timestamp])
  --logfile PATH       Log file path (default: [outdir]/list_prs.log)
  --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

## � Logging and Troubleshooting

The tool includes comprehensive logging to help diagnose issues. By default, logs are written to `/tmp/[user]/jps-ado-pr-utils/[timestamp]/list_prs.log`.

### Viewing Logs

```bash
# Run with default logging
jps-ado-pr-utils --project "MyProject"

# The log file location will be displayed in the output
# View the log file
tail -f /tmp/$USER/jps-ado-pr-utils/*/list_prs.log
```

### Custom Log Location

```bash
# Specify custom output directory
jps-ado-pr-utils --project "MyProject" --outdir /path/to/logs

# Specify custom log file
jps-ado-pr-utils --project "MyProject" --logfile /path/to/my.log
```

### Common Issues

**404 Error - Project not found:**
- You must specify the **Azure DevOps project name**, not the repository name
- Project names are case-sensitive
- Example: Use `--project "Engineering Team"` not `--project "backend-api"`
- To filter by repository, use: `--project "Engineering Team" --repos "backend-api"`

**No PRs showing up:**
- Check the log file for API errors
- Verify your project name is correct (case-sensitive)
- Ensure your PAT has Code (Read) permissions
- Try different status filters (--status completed, --status all)
- If filtering by --repos, verify the repository names are correct

**Authentication errors:**
- Verify AZDO_PAT is set correctly in ~/.config/jps-ado-pr-utils/.env
- Check that your PAT hasn't expired
- Ensure AZDO_USER matches your Azure DevOps email

## �🔧 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/)
