Metadata-Version: 2.4
Name: codeownerinsights
Version: 0.3.0
Summary: Parse GitHub's CODEOWNERS file and resolve code owners for a path, with optional git integration.
License-Expression: MIT
License-File: LICENSE
Keywords: codeowners,git,github,code-review,ownership
Author: Keith Hall
Author-email: keith.hall@available.systems
Requires-Python: >=3.11,<4.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Dist: wcmatch (>=10.0,<11.0)
Project-URL: Homepage, https://github.com/STealthy-and-haSTy/CodeOwnerInsights
Project-URL: Issues, https://github.com/STealthy-and-haSTy/CodeOwnerInsights/issues
Project-URL: Repository, https://github.com/STealthy-and-haSTy/CodeOwnerInsights
Description-Content-Type: text/markdown

# codeownerinsights

Parse GitHub's [`CODEOWNERS`](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners)
file and work out who owns a given file: which rules match it, and which one
wins. Pure Python, no editor dependency.

```sh
pip install codeownerinsights
```

Requires Python 3.8 or newer. The only runtime dependency is
[`wcmatch`](https://pypi.org/project/wcmatch/), for GitHub-compatible glob
matching.

## Usage

```python
from pathlib import Path

from codeownerinsights import (
    parse_code_owners,
    get_matching_code_owner_specifications_for_file,
    get_resolved_code_owners_for_file,
)

codeowners_path = Path('.github/CODEOWNERS')
codeowners = list(parse_code_owners(codeowners_path, codeowners_path.read_text(encoding='utf-8')))

# every rule that matches, in file order
for spec in get_matching_code_owner_specifications_for_file(codeowners, Path('src/main.py')):
    print(spec.glob_pattern, '->', spec.owners)

# the resolved owner: the last matching rule wins
owner = get_resolved_code_owners_for_file(codeowners, Path('src/main.py'))
print(owner.owners)
```

## What it gives you

**All matching rules, not just the winner.** Most parsers stop at the resolved
owner. `get_matching_code_owner_specifications_for_file` yields every rule that
hits a path, in file order, so you can show a user which earlier rule is being
overridden by a later one — or why an intended rule did not match at all.

**Nearest comment carried with each rule.** Every parsed
`CodeOwnerSpecification` remembers the comment block immediately above it, so a
rule can be presented with its documentation rather than as a bare pattern.

```python
spec.nearest_comment  # '# Frontend rules\n# owned by the web team'
spec.glob_pattern  # '/web/'
spec.owners  # ['@web-team']
spec.line_number  # 5
spec.codeowners_file_path
```

**GitHub's documented semantics, not git's.** Patterns follow GitHub's
`CODEOWNERS` rules literally: a leading `/` anchors the pattern to the repository
root, and a trailing `/` matches the directory and its contents. This is
deliberately *not* the `git check-ignore` convention where a leading slash means
"do not match". The asymmetry that matters in practice is between anchored and
unslashed directory patterns — with a `CODEOWNERS` at the repository root,
`docs/` matches `docs/readme.md` *and* `src/docs/readme.md`, while `/docs/` matches
`docs/readme.md` but not `src/docs/readme.md`. A slash in the middle anchors a
pattern just as a leading one does, so `docs/*` matches `docs/intro.md` but not
`src/docs/intro.md`. A pattern that matches a directory covers everything beneath it,
except that `docs/*` stops at the files directly inside `docs`.

Where the two differ, we follow GitHub. `git check-ignore` additionally supports
`!` to negate a pattern, `\` to escape a leading `#`, and `[ ]` character classes;
GitHub's `CODEOWNERS` docs list all three as unsupported, and this library does not
handle them. `test/test_matching.py` pins the matching rules, checked against how
GitHub itself resolves the `CODEOWNERS` files of public repositories.

**Locating the file.** `get_code_owners_file(root)` looks in the three places
GitHub searches, in GitHub's order, and returns the first hit:

```python
get_code_owners_file(Path('.'))
# .github/CODEOWNERS, CODEOWNERS, or docs/CODEOWNERS
```

## Command line

`codeownerinsights` (or `python -m codeownerinsights`) prints the owner of each
file and the rule that decides it, then the owners those files need. With no
arguments it uses the files the current branch changes compared with
`origin/<default>`, deletions included, which are the files GitHub requests a
pull request's reviewers for.

```sh
$ codeownerinsights
source/app/config/routes.php	@org/backend	CODEOWNERS:2 *
source/src/Model/Identity/User.php	@org/identity	CODEOWNERS:91 source/**/Identity/

Owners:
  @org/backend (1 file)
  @org/identity (1 file)
```

- Pass paths to resolve those files instead, relative to the current directory.
  `-` reads paths from stdin, so `git diff --name-only main... | codeownerinsights -`
  works too.
- `--repo <path>` resolves files against a repository other than the current git
  top level.
- `--base <ref>` compares with another ref, and `--no-fetch` skips refreshing
  `origin/<default>`.
- `--all-rules` lists every matching rule under each file and marks the one that
  applies with `*`. With `--json`, this includes `matching_rules` for each file.
- `--json` prints the same result as JSON, with an `owners` map from each owner
  to its files.
- `--git <executable>` uses a different git executable (default: `git`).

The exit code is 2 when the repository has no `CODEOWNERS` file.

## Git integration

`codeownerinsights.git` shells out to git to find what changed relative to a
branch, which is what you want to answer "who reviews this PR".

```python
from pathlib import Path
from codeownerinsights.git import get_git_changed_files_compared_to_default_branch

for changed in get_git_changed_files_compared_to_default_branch(Path('.')):
    print(changed)
```

By default this refreshes `origin/<default>` first, so the result reflects the
real remote baseline; pass `fetch_remote=False` to skip the network round trip
and accept a possibly stale baseline. Renamed files are reported under their new
path only, and deletions are dropped unless you pass `diff_filter='ACMRD'`.

Every helper accepts an optional `git=` parameter, so a wrapper can be
substituted by replacing the leading command token — useful for injecting
credentials:

```python
get_git_changed_files_compared_to_default_branch(Path('.'), git='my-git-wrapper')
```

No function changes the process working directory; commands run against the
folder passed in via `cwd=`. This matters in hosts like the Sublime Text plugin
host, where all packages share one interpreter.

## Status bar text

`status_text` renders a resolved rule into a status-bar line from a template,
for callers that want configurable wording.

```python
from codeownerinsights.status_text import render_status_text

render_status_text('Code Owner: {comment? - }{owners}', spec)
# 'Code Owner: Frontend rules owned by the web team - @web-team'
```

Available keys are `{owners}`, `{owner}` (the first owner only), `{comment}`,
`{pattern}`, `{line_number}` and `{codeowners_file}`. A key with nothing to say
renders as nothing and the surrounding whitespace is collapsed, so one template
serves every rule. A misspelled key is left in place rather than silently
blanked, and nothing raises on a bad template.

A key can be made conditional: `{key?text}` includes the literal `text` only
when the key has a value, and drops it when it does not. That is how the
example keeps the dash beside `{comment}` when there is a comment and omits it
when there is not, instead of leaving a stray dash behind.

## Used by

This library is the engine behind
[CodeOwnerInsights](https://github.com/STealthy-and-haSTy/CodeOwnerInsights), a
Sublime Text plugin that surfaces the current file's code owner in the status
bar.

## License

MIT.
