Metadata-Version: 2.4
Name: checkowners
Version: 0.3.0
Summary: Infer CODEOWNERS from git history with confidence scoring, knowledge graphs, expertise decay detection, bus factor analysis, and team topology inference. CI-native.
Project-URL: Homepage, https://github.com/smusali/checkowners
Project-URL: Issues, https://github.com/smusali/checkowners/issues
Project-URL: Source, https://github.com/smusali/checkowners
Author-email: Samir Musali <samir.musali@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: bus-factor,cli,code-review,codeowners,drift-detection,expertise-decay,git,github-actions,knowledge-graph,ownership,platform-engineering,team-topology
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: Topic :: Software Development :: Version Control :: Git
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
Provides-Extra: graph
Requires-Dist: networkx>=3.0; extra == 'graph'
Description-Content-Type: text/markdown

# checkowners

[![CI](https://github.com/smusali/checkowners/actions/workflows/ci.yml/badge.svg)](https://github.com/smusali/checkowners/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/checkowners.svg)](https://pypi.org/project/checkowners/)
[![PyPI downloads](https://img.shields.io/pypi/dm/checkowners.svg)](https://pypi.org/project/checkowners/)
[![Python versions](https://img.shields.io/pypi/pyversions/checkowners.svg)](https://pypi.org/project/checkowners/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

Infer CODEOWNERS from git history with confidence scoring, a knowledge graph, expertise decay detection, bus factor analysis, team topology inference, review load balancing, and onboarding paths. Pure git, no LLMs. CI-native: structured JSON output, GITHUB_OUTPUT integration, composite GitHub Action.

> Ownership is not binary. checkOwners is the first CODEOWNERS tool that treats it as a confidence-scored spectrum and surfaces the second-order risks (bus factor, expertise decay, team topology) that come with it.

## How it works

```mermaid
flowchart LR
    Git[Git history] --> Analyze[analyze]
    Analyze --> State[(state.json)]
    State --> Generate[generate]
    State --> Drift[drift]
    State --> Bus[bus-factor]
    State --> Decay[decay]
    State --> Topology[topology]
    State --> Balance[balance]
    State --> Onboard[onboard]
    Generate --> CO[CODEOWNERS]
    Drift --> CI[CI output]
```

## Installation

```bash
pip install checkowners               # core CLI
pip install "checkowners[graph]"      # adds networkx-backed graph / topology / onboard
```

## Quick start

```bash
# Confidence-scored ownership inference
checkowners analyze

# Write CODEOWNERS with owners ranked by expertise confidence
checkowners generate

# Compare inferred vs current CODEOWNERS, ranked by confidence delta
checkowners drift

# Validate syntax (no git access)
checkowners validate
```

All commands accept `--json` and persist their results to `~/.checkowners/state.json` so downstream commands can reuse the analysis.

## Commands

| Command | What it does |
|---------|--------------|
| `checkowners analyze` | Infer ownership with confidence scores, bus factor, decay warnings |
| `checkowners generate` | Write CODEOWNERS, ordered by confidence; optional inline annotations |
| `checkowners print` | Print inferred ownership to stdout |
| `checkowners validate` | Validate existing CODEOWNERS syntax |
| `checkowners drift` | Compare inferred vs current; severity + max confidence delta |
| `checkowners notify` | POST drift to a webhook gated by `severity_threshold` |
| `checkowners sync` | Generate CODEOWNERS and commit the result |
| `checkowners expertise <path>` | Per-path expertise ranking |
| `checkowners decay` | Detect dormant owners; recommend transfers |
| `checkowners graph [--export dot]` | Render the contributor / file / team graph |
| `checkowners bus-factor [<path>] [--all]` | Per-path bus factor with backup-reviewer suggestions |
| `checkowners topology` | Infer team boundaries from commit co-occurrence |
| `checkowners balance` | Detect overloaded reviewers and propose rebalancing |
| `checkowners onboard <path>` | Generate a learning path from broad-ownership to deep-expertise files |

## Documentation

- [docs/USAGE.md](docs/USAGE.md): full configuration reference, confidence scoring formula, drift severity tiers, GitHub Actions integration, comparison table.
- [docs/FAQ.md](docs/FAQ.md): identity (usernames vs emails, teams + subteams), GitHub API access, file locations, tuning, troubleshooting.
- [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md): dev setup, commands, conventional commits, code conventions, PR workflow.
- [docs/CHANGELOG.md](docs/CHANGELOG.md): release history.

## License

MIT
