jjmschofield / github-codeowners

github-codeowners

A CLI tool for working with GitHub CODEOWNERS.

Things it does:

• Calculate ownership stats
• Find out who owns each and every file (ignoring files listed in .gitignore)
• Find out who owns a single file
• Find out who owns your staged files
• Outputs in a bunch of script friendly handy formats for integrations (CSV and JSONL)
• Validates that your CODEOWNERS file is valid

Installation

Install via npm globally then run

$ npm i -g github-codeowners
$ github-codeowners --help 
Usage: github-codeowners [options] [command]

Commands

Audit

Compares every file in your current (or specified) directory against your CODEOWNERS rules and outputs the result of who owns each file.

$ cd <your awesome project> 
$ github-codeowners audit
README.md
package.json
src/cli.ts      @jjmschofield
...

Ownership stats:

$ github-codeowners audit -s
--- Counts ---
Total: 24 files (1378 lines)
Loved: 10 files (494 lines)
Unloved: 14 files (884 lines)
--- Owners ---
@jjmschofield: 10 files (494 lines)

Only files in a specific directory:

$ github-codeowners audit -r src/
src/cli.ts      @jjmschofield
src/commands/audit.ts   @jjmschofield
...

Only unowned files:

$ github-codeowners audit -u
.github/CODEOWNERS
.gitignore

Output in JSONL:

$ github-codeowners audit -o jsonl
{"path":"src/commands/audit.ts","owners":["@jjmschofield"],"lines":48}
...

Output in CSV:

$ github-codeowners audit -o csv
src/commands/audit.ts,@jjmschofield

Full usage information:

$ github-codeowners audit --help
Usage: github-codeowners audit [options]

list the owners for all files

Options:
  -d, --dir <dirPath>          path to VCS directory (default: "<current working directory>")
  -c, --codeowners <filePath>  path to codeowners file (default: "<dir>/.github/CODEOWNERS")
  -o, --output <outputFormat>  how to output format eg: simple, jsonl, csv (default: "simple")
  -u, --unloved                unowned files only (default: false)
  -g, --only-git               consider only files tracked by git (default: false)
  -s, --stats                  output stats (default: true)
  -r, --root <rootPath>        the root path to filter files by (default: "")
  -h, --help                   output usage information

Who

Tells you who owns a given file or files:

$ cd <your awesome project> 
$ github-codeowners who <file> <file>
<file> @some/team
<file> @some/team

Full usage:

$ github-codeowners who --help                   
Usage: github-codeowners who [options] <file...>

lists owners of a specific file or files

Options:
  -d, --dir <dirPath>          path to VCS directory (default: "/Users/jjmschofield/projects/github/snyk/registry")
  -c, --codeowners <filePath>  path to codeowners file (default: "<dir>/.github/CODEOWNERS")
  -o, --output <outputFormat>  how to output format eg: simple, jsonl, csv (default: "simple")
  -h, --help                   output usage information

Git

Provides a list of files with their owners between commits (against the current version of CODEOWNERS).

Ownership of all files staged for commit:

$ cd <your awesome project>
$ github-codeowners git

Ownership of files existing at a specific commit:

$ github-codeowners git <commit sha>

Ownership of files changed between two commits:

$ github-codeowners git <commit sha> <commit sha>

Output stats:

$ github-codeowners git -s

Full usage:

$ github-codeowners git --help                                                                                       
Usage: github-codeowners git [options] [shaA] [shaB]

lists owners of files changed between commits, a commit against head or staged against head.

Options:
  -d, --dir <dirPath>          path to VCS directory (default: "/Users/jjmschofield/projects/github/snyk/registry")
  -c, --codeowners <filePath>  path to codeowners file (default: "<dir>/.github/CODEOWNERS")
  -o, --output <outputFormat>  how to output format eg: simple, jsonl, csv (default: "simple")
  -s, --stats                  output stats, note line counts are not available for this command (default: false)
  -h, --help                   output usage information

Validate

Validates your CODEOWNERS file to find common mistakes, will throw on errors (such as malformed owners).

$ cd <your awesome project> 
$ github-codeowners validate
Found duplicate rules [ 'some/duplicate/rule @octocat' ]
Found rules which did not match any files [ 'some/non-existent/path @octocat' ]
...

Full usage information:

$ github-codeowners validate --help
Usage: github-codeowners validate [options]

Validates a CODOWNER file and files in dir

Options:
  -d, --dir <dirPath>          path to VCS directory (default: "<current working directory>")
  -c, --codeowners <filePath>  path to codeowners file (default: "<dir>/.github/CODEOWNERS")
  -r, --root <rootPath>        the root path to filter files by (default: "")
  -h, --help                   output usage information

Output Formats

Check github-codeowners <command> --help for support for a given command, however generally the following outputs are supported:

• simple - tab delimited - terminal friendly output
• jsonl - line separated json - useful for streaming data to another command
• csv - csv delimited fields - useful to import into a spreadsheet tool of your choice

Limits and Things to Improve

• It requires node
• It is not optimized
• The output interface might change
• Command syntax might change

Shout outs

Inspired by codeowners but implemented in Typescript with extra bells and whistles.

github-codeowners's Issues

symlinks break directory reading

Despite wide usage, maintainer of underlying lib is seems to no longer be maintaining jergason/recursive-readdir#60

Replace lib.

Add validation for owner names

Add a regex check when reading in code owners to ensure that owner names are valid for github.

Github has two potential formats for an owner which are valid:

• [email protected]
• @js-owner

https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/about-code-owners

support multiple files on the who command

based on https://github.com/jjmschofield/github-codeowners/pull/43/files from @FauxFaux

avoid counting lines if the config doesn't require a line count

prevents loading files into memory if not required, perf improvement suggestion from @FauxFaux

publish from ci

add tests

support a whitelist of owners for validate

To help people support the schema at https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/about-code-owners

Where in:

"Invalid syntax includes inline comments and user or team names that do not exist on GitHub."

In a config (somehwere, somehow) create a list of allowed owners and make the validate command respect it.

{
  ...
  "validate":{
    ...
    "owners": {
      "allowed": [
        "@bob"
      ]
    }
  }
}

add a version command

git: option to exclude deleted files

I'm using this as a CI step to require explicit owners for a monolith owned by multiple teams. Currently the CI step will fail if someone deletes a file that didn't have an explicit owner. This is obviously not desirable.

It would be nice to have an option like:

github-codeowners git --exclude-deleted-files develop HEAD

This way the CI can enforce that all new or modified files have owners.

add support for stats buckets

validate should not allow inline comments

As per:

"Invalid syntax includes inline comments and user or team names that do not exist on GitHub."

https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/about-code-owners

library interface

Offer up a dependable interface so that other apps / scripts can consume the core functionality

setup ci

files with multiple dots in the file name not matched

I'm told I have a validation error:

$ github-codeowners validate
Found rules which did not match any files [
  '/test.en.yml @org/team',
]

But in reality the file exists:

$ ls test.en.yml
test.en.yml

Had a browse around the codebase and didn't spot the bug, sorry.

create specific stats command

Bug: Currently owners are augmented

If multiple lines define ownership for a file then the owners are augmented.

The expected result would be that the later definitions overwrites earlier ones as stated here: codeowners-syntax

This is especially wrong for * ownerships.

Error when using -s and -g flags and a submodule is present

Steps to reproduce

• In a git repo, add a submodule
• run github-codeowners audit -s -g
• See the error message:

failed to read lines from file github-codeowners [Error: EISDIR: illegal operation on a directory, read]

Output from terminal

Expected behavior

Ownership stats should be shown as expected without any error.
Submodules should be excluded, or included via a new parameter.

add unit tests

Owners list ordering in audit output could be improved

It currently seems a bit random. I think alphabetically by team name is a good start. Other ideas are by number of files owned.

feat: audit unloved should support explicitly unowned

Hey @jjmschofield, thanks much for this awesome library! 💯 Are you currently accepting contributions? And if so, would you possibly have time to review, merge, and publish? If not, I understand - I'm happy to fork.

I'd love for github-codeowners audit --unloved to support the use case of explicitly marking some files as unowned. My use case is basically to enforce 100% CODEOWNERS coverage by ensuring this command has no output, but then allowing some known exceptions to be explicitly listed in the CODEOWNERS file.

GitHub appears to support this: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners#:~:text=owners%20are%20left%20empty

# In this example, @octocat owns any file in the /apps
# directory in the root of your repository except for the /apps/github
# subdirectory, as its owners are left empty.
/apps/ @octocat
/apps/github

Historically I'd been using @ghost entries, but GitHub's recent feature to present a UI for validation of files shows errors because that is not a real team.

nested gitignore support

Currently only the root .gitignore is respected

add integration tests

Validate: Can't use unix pipes or return code

$ github-codeowners validate
Found rules which did not match any files [
  '/some_file.yml @team'
]
$ echo $?
0

I would have expected this to return an error.

Further I tried to work around this by using wc -l but no dice:

$ github-codeowners validate | wc -l
Found rules which did not match any files [
  '/some_file.yml @team'
]
       0

Incorrect handling of wildcard and subdirectories

It is possible to "fool" this library into thinking a file is covered by codeowners, whilst GitHub will not apply code ownership.

Steps to reproduce

• Create a file in some nested subdirectory, e.g. /foo/bar/baz.txt
• Add a rule involving a wildcard to CODEOWNERS e.g. /foo/* or /foo/b*
• Run github-codeowners audit

Expected

• The file is considered unloved

Actual

• The file is considered loved

Notes

I've tested this scenario by raising a PR (in a private repo), and GitHub did not assign any code owners.

add shared ownership stats

add better error handling when no CODEOWNERS