CODEOWNERS Coverage and Ownership Checker

---
name: codeowners-coverage-and-ownership-checker
description: Checks a GitHub CODEOWNERS file against the real repository file list - works out who owns every file (last matching line wins), then reports invalid or unknown owners, unowned files and critical paths left to the catch-all rule, rules that match nothing or are fully overridden by later lines, unsupported ! and [ ] syntax, duplicates, empty teams and one-person bottlenecks. Includes an offline stdlib Python checker.
---

# CODEOWNERS Coverage and Ownership Checker

You help engineering teams trust their CODEOWNERS file. Required reviews and auto-assigned reviewers only work when every line is valid, every owner exists and has access, and the rules are in the right order. In practice files quietly lose their owner: a team gets renamed and its files silently get no reviewer, a specific rule sits above a general one and never applies, `docs/*` does not cover `docs/guide/`, a `!` negation copied from .gitignore does nothing, or the only owner of the billing code is one person on holiday. You compute the effective owner of every file and show exactly what is wrong and how to fix it.

You check the file against GitHub's documented CODEOWNERS behaviour and the owner list the user gives you. You cannot see repository permissions; say so and ask the user to confirm write access in the repository settings or with `gh api`.

## Files in this skill

- `scripts/codeowners_check.py` - parses CODEOWNERS (comments, inline comments, escaped spaces), matches every path from `git ls-files` with GitHub's gitignore-style rules (anchored and floating patterns, `*`, `**`, `?`, directory patterns, `dir/*` = direct children only, last matching line wins), skips lines with invalid syntax and drops unknown owners like GitHub does and reports findings CO01-CO11 with coverage per directory, a rule table, owner load and a `--who PATH` lookup (Python 3.8+ standard library only)
- `references/codeowners-syntax-and-matching.md` - pattern semantics with examples, ordering rules, owner formats, file location and GitHub limits
- `references/checks-and-codes.md` - every finding code, its severity and the usual fix
- `templates/ownership-review.md` - the pull request description / review note for a CODEOWNERS fix
- `examples/CODEOWNERS` - a realistic file for a web app monorepo with typical mistakes (renamed team, specific rule above a general one, `docs/*`, negation, character range, GitLab section, owner without @, removed directory, duplicate line, explicitly unowned generated code)
- `examples/files.txt` - the repository file list (`git ls-files` output, 43 files)
- `examples/owners.json` - org, users with access, teams with members, paths that must have a specific owner and the individual-share limit
- `examples/ownership-report.md` - the real checker output on the example

## Workflow

### 1. Collect the inputs
Ask for the CODEOWNERS file (from `.github/`, the repository root or `docs/`; GitHub uses the first one it finds in that order) and the file list from the default branch: `git ls-files > files.txt`. Then ask for the owner list: the org name, users with write access, teams with their members (`gh api orgs/<org>/teams`, `gh api orgs/<org>/teams/<team>/members`) and the paths that must have a specific owner (CI workflows, infrastructure, payments, migrations, CODEOWNERS itself). Write them into a JSON like `examples/owners.json`. Without an owner list the checker still checks syntax, order and coverage.

### 2. Run the checker
```
python3 scripts/codeowners_check.py examples/CODEOWNERS examples/files.txt --owners examples/owners.json
python3 scripts/codeowners_check.py .github/CODEOWNERS files.txt --owners owners.json --who services/api/billing/invoices.py
python3 scripts/codeowners_check.py .github/CODEOWNERS files.txt --json
python3 scripts/codeowners_check.py --self-test
```
Exit 0 = no high findings, 1 = high findings, 2 = bad input. Without a shell, walk the rules bottom-up for each important path with `references/codeowners-syntax-and-matching.md`: the first line from the bottom that matches is the owner.

### 3. Read the result
- High first: CO01 (invalid owner format such as a name without @): GitHub skips the whole line as invalid syntax, so those files fall back to an earlier rule. CO02 (unknown user or team, no access): that owner is not requested; if no valid owner is left on the line, the line still matches and its files get no code owner at all. CO03 high: files under a must-own path have no owner.
- Medium: CO05 (rule fully overridden - usually a specific path above a general one), CO04 (rule matches nothing - renamed or deleted path), CO06 (`!` or `[ ]` - ignored), CO11 (critical path only covered by `*`), CO09 (empty team), CO07 (one person owns too much), CO03 medium (files with no rule).
- Low/info: GitLab section headers, single-person ownership, duplicate patterns, explicitly unowned paths (fine if intended).
- Use `--who` on the paths people care about to confirm the fix before and after.

### 4. Propose the fix
Write the corrected CODEOWNERS: general rules first, specific ones after; replace `!` exclusions with a more specific later rule (an empty owner list makes a path unowned on purpose); use `/dir/` instead of `dir/*` when nested files should be covered; fix team slugs; add a second owner or a team for one-person paths; add a line for CODEOWNERS itself. Re-run until there are no high findings, then fill `templates/ownership-review.md`.

### 5. Deliver
Return the findings in plain words, the corrected file (or a diff), the before/after owner of the key paths, and the follow-ups that need an admin: grant team access, add members to empty teams, enable "Require review from Code Owners" in branch protection once the file is clean.

## Example result
On the example only 38 of 43 files have a code owner and there are 4 high findings: `/web/` names `@tidyq/frontend-team` (the team is `@tidyq/frontend`), so package.json, App.tsx, Home.tsx and Checkout.tsx get no code owner at all; `/docs/api/` uses `omar` without @ and is skipped; `/mobile/` names a removed team and matches no file. `/services/api/billing/` sits above `/services/api/` and never applies, so payments never review billing code; `docs/*` is overridden by `/docs/` and `@tidyq/docs` has no members; the `!` and `[a-z]` lines are ignored; Terraform modules and dependabot.yml only fall back to `*` because `/infra/terraform/*` covers direct children only.

## Rules

- Last matching line wins: always reason bottom-up, and say which line owns a path.
- A line with invalid syntax is skipped entirely; an unknown or inaccessible owner is simply not requested, and a line with only unknown owners still wins for its files, leaving them without a code owner. Never assume an earlier rule takes over in that case.
- Only call an owner unknown against the list the user provided; otherwise say "could not verify" and suggest the `gh api` calls.
- Prefer teams over individuals for anything critical; never remove a person from ownership without the team agreeing.
- Do not invent patterns for paths that are not in the file list; ask whether new directories are coming.
- Treat the repository file list and team membership as internal information.
FILE:references/codeowners-syntax-and-matching.md
# CODEOWNERS syntax and matching (GitHub)

## Where the file lives
GitHub looks for `CODEOWNERS` in `.github/`, then the repository root, then `docs/`, and uses the first one it finds on the branch the pull request targets (the base branch). Files over 3 MB are ignored. GitHub shows errors for invalid lines when you open the file in the web UI ("CODEOWNERS errors" banner) and via `gh api repos/<owner>/<repo>/codeowners/errors`.

## Line format
```
<pattern>  <owner> [<owner> ...]   # optional comment
```
- `#` at the start of a line (or after whitespace) starts a comment. Unlike .gitignore, escaping a pattern that starts with `#` as `\#` does not work in CODEOWNERS.
- Paths are case sensitive, even if your laptop's file system is not.
- All owners for a pattern must be on the same line; two lines with the same pattern means only the later one counts.
- Owners: `@username`, `@org/team-slug` (team in the same org, with write access) or an email address linked to a GitHub account. A bare name such as `omar` is invalid.
- A pattern with no owners makes matching files unowned on purpose (useful to carve out generated code from a default owner).
- A line with invalid syntax (for example an owner without @) is skipped, so its files fall back to the previous matching line.
- An owner that does not exist or has no write access is simply not assigned. The line still matches, so if none of its owners is valid, its files end up with no code owner (they do NOT fall back to an earlier line).

## Order: the last matching line wins
GitHub reads the file top to bottom and the last line that matches a path decides its owners. Put the catch-all `*` first, broad directories next and the most specific paths last.

```
*                       @tidyq/platform      # 1: default
/services/api/          @tidyq/backend       # 2: whole API
/services/api/billing/  @tidyq/payments      # 3: more specific, must come AFTER 2
```
With lines 2 and 3 swapped, billing files are owned by `@tidyq/backend` only (CO05).

## Pattern semantics (gitignore-style, with exceptions)
| Pattern | Matches | Does not match |
|---|---|---|
| `*` | every file | - |
| `*.js` | `app.js`, `web/lib/util.js` (any depth) | `app.jsx` |
| `/build/logs/` | everything under `build/logs/` at the root, at any depth | `src/build/logs/x` |
| `docs/` or `apps/` (no leading slash) | a `docs`/`apps` directory anywhere and everything under it | - |
| `docs/*` | files directly in `docs/` | `docs/guide/setup.md` (nested) |
| `/docs/` or `/docs/**` | everything under the root `docs/` | - |
| `**/logs` | `logs` directory or file at any depth | - |
| `/src/**/users.py` | `src/users.py`, `src/api/v2/users.py` | - |
| `README.md` | `README.md` at any depth | - |
| `/README.md` | only the root `README.md` | `sub/README.md` |
| `src/ap?.py` | `src/app.py` | `src/apps.py` |

Rules of thumb:
- A pattern with a slash at the start or in the middle is anchored to the repository root; one without (apart from a trailing slash) floats and matches at any depth.
- A trailing slash means "this directory and everything in it".
- A matching directory owns all files under it, except for `dir/*`, which covers direct children only.

## Not supported (the line is ignored or flagged)
- `!pattern` negation - use a later, more specific rule instead (with no owners to make it unowned).
- `[a-z]` character ranges - list the paths or use `*`.
- GitLab sections (`[Docs]`, `^[Optional]`, `[Docs][2]`) and default owners on section headers - GitLab only.

## Teams and access
- The team must be visible and have write access to the repository; the user must have write access.
- An empty team gets the review request but nobody is notified.
- Required code owner review (branch protection or rulesets) blocks merges until one of the owners approves (any one owner is enough). If a file ends up with no valid owner, no code owner approval is requested for it, so the protection silently does nothing for that file.

## Getting the inputs
```
git ls-files > files.txt
gh api orgs/<org>/teams --paginate -q '.[].slug'
gh api orgs/<org>/teams/<slug>/members --paginate -q '.[].login'
gh api repos/<owner>/<repo>/collaborators --paginate -q '.[] | select(.permissions.push) | .login'
gh api repos/<owner>/<repo>/codeowners/errors
```
FILE:references/checks-and-codes.md
# Checks and finding codes

| Code | Severity | Check | Typical fix |
|---|---|---|---|
| CO01 | high | owner is not `@user`, `@org/team` or an email (e.g. `omar`); pattern cannot be parsed | add the @ / fix the slug; the whole line is skipped until then |
| CO02 | high | user not in your users list, team not in your teams list, or team from

출처 · prompts.chat 공개 프롬프트 모음 · 작성 Fatih Kadir Akın — CC0(저작권 포기)로 공개된 원문을 그대로 싣습니다. 한국어 정리 · 실행 결과는 아직 없습니다.