checkowners 0.3.0

Infer CODEOWNERS from git history with confidence scoring, knowledge graphs, expertise decay detection, bus factor analysis, and team topology inference. CI-native.

checkowners

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

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

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

Quick start

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

License

MIT