Metadata-Version: 2.4
Name: checkowners
Version: 0.1.0
Summary: Infer and maintain CODEOWNERS from git history. Drift detection, CI-native JSON output, and GitHub Actions integration.
Author-email: Samir Musali <samir.musali@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: cli,codeowners,drift-detection,git,github-actions,ownership
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: gitpython>=3.1.0
Requires-Dist: pygithub>=2.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0.0
Requires-Dist: typer>=0.9.0
Description-Content-Type: text/markdown

# checkowners

[![PyPI version](https://img.shields.io/pypi/v/checkowners)](https://pypi.org/project/checkowners/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

Infer and maintain CODEOWNERS from git history. Drift detection, CI-native JSON output, and GitHub Actions integration.

## Installation

```bash
pip install checkowners
```

## Quick Start

```bash
# Infer ownership from git commit history
checkowners analyze

# Generate .github/CODEOWNERS from inference
checkowners generate

# Detect drift between inferred and current CODEOWNERS
checkowners drift

# Validate CODEOWNERS syntax
checkowners validate
```

All commands support `--json` for structured output.

## Commands

| Command | Description |
|---------|-------------|
| `checkowners analyze` | Infer file ownership from git history |
| `checkowners generate` | Write `.github/CODEOWNERS` from inferred ownership |
| `checkowners print` | Print inferred owners to stdout |
| `checkowners validate` | Validate existing CODEOWNERS syntax (no git access) |
| `checkowners drift` | Compare inferred vs. current CODEOWNERS |
| `checkowners notify` | POST webhook on drift events |
| `checkowners sync` | Generate CODEOWNERS and commit the result |

## Configuration

Create `.github/checkowners.yml` in your repository:

```yaml
analysis:
  lookback_days: 180        # How far back to analyze
  min_commits: 3            # Minimum commits to qualify as owner
  top_n_owners: 2           # Max owners per path

paths:
  exclude:
    - "*.lock"
    - "dist/**"
    - "vendor/**"

output:
  header: "# Generated by checkOwners. Do not edit manually."
  include_unowned: false    # Show paths with no inferred owner

drift:
  mode: commit              # commit | repo | both
  compare_to: auto

notifications:
  webhook_url: ""           # POST here on drift events
  include_unchanged: false
```

All fields are optional. Defaults are shown above.

## Drift Detection Modes

- **commit**: detect paths in the inferred map that are missing from CODEOWNERS
- **repo**: detect CODEOWNERS entries that are stale or have changed owners
- **both**: run both checks

## GitHub Actions

```yaml
- name: Check CODEOWNERS drift
  run: |
    pip install checkowners
    checkowners drift --json
```

Set `drift.mode: both` in your config and fail the step when `drift_detected` is true.

## Development

```bash
hatch run test              # pytest with coverage
hatch run lint              # ruff check + mypy --strict
hatch run fmt               # ruff format
```

## License

MIT
