ctrl+shift+p filters: :st2 :st3 :win :osx :linux
Browse

Code​Owner​Insights

Sublime Text plugin to help identify the GitHub CODEOWNERS of the current file

Labels codeowners, github

Details

Installs

  • Total 40
  • Win 18
  • Mac 14
  • Linux 8
Nov 22 Nov 21 Nov 20 Nov 19 Nov 18 Nov 17 Nov 16 Nov 15 Nov 14 Nov 13 Nov 12 Nov 11 Nov 10 Nov 9 Nov 8 Nov 7 Nov 6 Nov 5 Nov 4 Nov 3 Nov 2 Nov 1 Oct 31 Oct 30 Oct 29 Oct 28 Oct 27 Oct 26 Oct 25 Oct 24 Oct 23 Oct 22 Oct 21 Oct 20 Oct 19 Oct 18 Oct 17 Oct 16 Oct 15 Oct 14 Oct 13 Oct 12 Oct 11 Oct 10 Oct 9
Windows 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
Mac 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
Linux 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0

Readme

Source
raw.​githubusercontent.​com

CodeOwnerInsights

A Sublime Text plugin to help identify the “code owner” of the current file. Parses GitHub's CODEOWNERS file and resolves the owner for the focused tab and shows it in the status bar. Includes command palette entries to open the CODEOWNERS file at the relevant line and to list every rule that matches.

The parsing, matching, and git logic live in a small framework-agnostic library published to PyPI as codeownerinsights. The plugin is just a thin Sublime wrapper around it, so the core behaviour can be imported and unit tested from any Python environment.

Status

This project is still in it's early stages, but works well. It was written for my personal use, but any bugs reported will be fixed. Feature requests will be considered, bonus points if you raise a Pull Request.

Settings live in CodeOwnerInsights.sublime-settings and are editable from Preferences → Package Settings → CodeOwnerInsights → Settings.

Setting Description
status_bar_template Text shown in the status bar for the current file's code owner. See below.
fetch_remote_default_branch Whether the diff command refreshes origin/<default> first, at the cost of a network round trip.

The status bar text is a template. Wrap any of these keys in braces and they are replaced with values from the rule that resolved for the current file:

Key Replaced with
{owners} Every owner on the rule, comma separated.
{owner} Just the first owner.
{comment} The comment above the rule, flattened onto one line.
{pattern} The glob pattern that matched.
{line_number} The line the rule is on in its CODEOWNERS file.
{codeowners_file} Path to the CODEOWNERS file the rule came from.

The default is "Code Owner: {comment? - }{owners}". A key with nothing to say — {comment} on a rule with no comment above it, say — renders as nothing and the whitespace around it is collapsed, so a single template works for every rule rather than needing a special case per rule. A misspelled key is left in place rather than silently blanked, so it is obvious what went wrong. Setting the template to "" hides the status bar entirely.

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 default template keeps the dash beside {comment} when there is a comment and omits it when there is not, instead of leaving a stray dash behind.

There is experimental support for showing the files a pull request from the current branch would change, grouped by code owner. You will find it in the command palette. Like GitHub, it counts committed changes only and resolves owners with the base branch's CODEOWNERS file, so it shows the reviewers the pull request will request. Currently very ugly but gets the job done.

Commands

Command Description
CodeOwnerInsights: Reveal Owner Open the CODEOWNERS file on the line whose rule resolves to the current file.
CodeOwnerInsights: Show All Matching Code Owner Rules Quick panel listing every CODEOWNERS rule that matches the current file, with the nearest comment shown under each pattern. The resolved owner (the last matching rule) is pre-selected. Preview opens the matching line; confirming a selection leaves the editor on that line; Esc cancels any preview navigation.
CodeOwnerInsights: Show Code Owners for git changes compared to default branch Group the files the branch's commits change relative to the default branch by the code owner that the default branch's CODEOWNERS gives them.

The “Show All Matching Code Owner Rules” command is bound to Ctrl+Shift+O.

What sets this apart

Most CODEOWNERS parsers stop at the resolved owner — the last matching rule. This project keeps the full match list, which is the whole point of the “Show All Matching Code Owner Rules” command: it lets you confirm an intended rule matches and see exactly which later line overrides it.

  • All matching rules, not just the winner. get_matching_code_owner_specifications_for_file yields every rule that hits a path, in file order; get_resolved_code_owners_for_file returns only the last one.
  • Nearest comment carried with each rule. Each parsed CodeOwnerSpecification remembers the comment block immediately above it, so a rule can be shown with its documentation rather than as a bare pattern.
  • Git-aware. The library wraps git to enumerate changed files relative to the remote default branch (origin/<default>), refreshing the tracking ref first so a stale local baseline doesn't drag unrelated commits into the diff. It reads CODEOWNERS at the base branch too, because that is the version GitHub uses to request reviewers. The git helpers accept an optional git= parameter so a git wrapper can be substituted by replacing the leading command token.
  • GitHub's documented semantics, not git's. Patterns follow GitHub's CODEOWNERS rules literally — a leading / anchors to the repo root and a trailing / matches the directory and its contents. This is deliberately not the git check-ignore convention where a leading slash means “don't match”. Where the two diverge, we follow GitHub: git check-ignore additionally supports ! to negate a pattern, \ to escape a leading #, and [ ] character classes, all of which GitHub's CODEOWNERS docs list as unsupported. They do agree on directory and anchoring rules.

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's commits change compared with origin/<default>, deletions included, which are the files GitHub requests a pull request's reviewers for. Uncommitted changes are left out, as they are not part of the pull request yet. Like GitHub, it reads CODEOWNERS from the base branch for these, and names the ref it used at the end of the output.

$ 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, one per line.
  • --root-relative takes the paths as relative to the repository root, which is how git prints them, and -z reads NUL-separated paths from stdin. So git diff --name-only -z main... | codeownerinsights --root-relative -z - works from any directory, whatever the file names contain.
  • --with-uncommitted adds uncommitted changes, untracked files included, to the branch changes: the files the pull request would change once everything is committed.
  • --staged resolves the files changed in the index instead, and --unstaged the files changed in the working tree plus untracked files that are not ignored. Pass both for every uncommitted change. Neither combines with paths, --base, --no-fetch or --with-uncommitted.
  • --codeowners-ref <ref> reads CODEOWNERS at another ref, and --worktree-codeowners reads the working tree's copy for the branch changes too, to preview edits to it. Other modes read the working tree's copy unless --codeowners-ref is given.
  • --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>.
  • --owner <owner> shows only the files that owner covers, and --not-owner <owner> leaves them out; repeat either for several owners. Case is ignored, and the @ and the org are optional, so --owner core-banking matches @TransferGo/core-banking. A file with several owners is covered by each of them, so --not-owner drops it if any of them is named.
  • --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.
  • --group-by owner lists the files under each set of owners that applies to them, with the deciding rule beside each file. A review from any one owner in a set covers its files. Text output only.
$ codeownerinsights --group-by owner
  @org/backend (1 file)
    source/app/config/routes.php        CODEOWNERS:2 *

  @org/identity (1 file)
    source/src/Model/Identity/User.php  CODEOWNERS:91 source/**/Identity/
  • --color auto|always|never colours the text output. auto, the default, colours it only when stdout is a terminal and NO_COLOR is not set, so pipes get plain text.
  • --json prints the same result as JSON, with an owners map from each owner to its files, and codeowners_ref, the ref CODEOWNERS was read at (null for the working tree).
  • --git <executable> uses a different git executable (default: git).

The exit code is 2 when there is no CODEOWNERS file where it was looked for, and 1 when the default branch cannot be found from origin/HEAD (pass --base).

Library usage

from pathlib import Path
from codeownerinsights.codeowners 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 (last match wins)
owner = get_resolved_code_owners_for_file(codeowners, Path('src/main.py'))

Development

To run the parser tests, in a terminal emulator:

python3 -m venv ./.venv
source .venv/bin/activate
pip install poetry
poetry install --no-root
deactivate # to avoid problems later
.venv/bin/poetry run pytest

The tests also run in CI on every push and pull request, in .github/workflows/test.yml.