snyk / github-codeowners Goto Github PK

View Code? Open in Web Editor NEW

8.0 61.0 10.0 257 KB

JavaScript 9.76% TypeScript 90.24%

github-codeowners's Introduction

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) 100%
Loved: 10 files (494 lines) 41.6%
Unloved: 14 files (884 lines) 58.4%
--- Owners ---
@jjmschofield: 10 files (494 lines) 41.6%

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.

This project is a fork of jjmschofield's version.

github-codeowners's People

Contributors

Stargazers

Watchers

Forkers

isabella232 elijaholmos chdsbd blackchoey bartveneman algotec segmentio andrej-p spyrosk apolloio

github-codeowners's Issues

ERR_CHILD_PROCESS_STDIO_MAXBUFFER when running `audit -g -s`

Hi all.
Thanks for maintaining this project. I am getting an error when running the audit command. I think it is caused by https://github.com/snyk/github-codeowners/blob/main/src/lib/file/readGit.ts#L5 which reads the entire git ls-files

Changing that line to:

const { stdout } = await exec('git ls-files', { cwd: dir, maxBuffer: 1024 * 1024 * 1024 });

Fixes the error, although the command is slower. For context, here is the beginning of the output:

--- Counts ---
Total: 62265 files (11911663 lines) 100%
Loved: 57515 files (7899241 lines) 66.32%
Unloved: 4750 files (4012422 lines 33.68%

I think this command could be optimized by listening to events on child processes and processing the data as a stream, perhaps using iterators or event listeners. I would be willing to take a shot at making this change in a PR, but I would like to gauge interest in such a change. Thanks for taking the time to look at my issue.

Add parsing options to support GitLab syntax

It does say in the name that this isn't intended for GitLab but besides the obvious --codeowners option, how much work for the package would it be to be able to skip section headings within the codeowners file? For this sample GitLab syntax, that means skipping lines 1 and 5

[First Section]
some/path/one/a  @one
some/path/one/b  @one

[Second Section]
some/path/two    @two

Expose API

Hey, I like your tool. Do you plan to export also some functionality of it in TypeScript so it can be reused to build tools on top of your solution? That would be great. :)

Feature Request: provide the matched pattern

I'm using github-codeowners who --output=jsonl <changed files> to add details to our GitHub pull requests. This informs our reviewers what files triggered there need to review.

It would be awesome if the JSON included the pattern in the CODEOWNERS file that matched.

If I had that I will sort the by pattern and create a easier to read list for the reviewers.

Thank you for this great tool.

Set exit-code to non-zero when unloved-files is bigger than 0

I want to run github-codeowners audit --unloved and have the CI fail if there are any unloved files (our policy is that every file needs an explicit owner). The same goes for running github-codeowners validate, if that finds any entries that do not exist in the file system.
The best way for this would be to set the exit code to a non-zero code so that GitHub Actions (or any other tool) recognizes that the check failed.

bug: improper parsing of CRLF EOL

Summary

While playing around with the package, I discovered a bug in how it parses CODEOWNERS files on windows vs macos/linux operating systems, specifically when the EOL sequence is set to CRLF instead of LF.

Steps to reproduce:

Environment: Windows 10 21H1, Node v16.18.0, NPM v8.19.2

Clone repository
$ npm ci
create test.js in root directory with contents:

const { OwnershipEngine } = require('./dist/lib/ownership');

const codeownersEngine = OwnershipEngine.FromCodeownersFile('.github/CODEOWNERS');
console.log(codeownersEngine.calcFileOwnership('.github/CODEOWNERS'));

$ npm run build
$ node test

Actual Output

C:\coding-work\github-codeowners>node test     
failed to load codeowners file from .github/CODEOWNERS Error:  is not a valid owner name in rule * @snyk/arch
    at createMatcherCodeownersRule (C:\coding-work\github-codeowners\dist\lib\ownership\OwnershipEngine.js:72:23)
    at Function.FromCodeownersFile (C:\coding-work\github-codeowners\dist\lib\ownership\OwnershipEngine.js:50:28)
    at Object.<anonymous> (C:\coding-work\github-codeowners\test.js:3:42)
    at Module._compile (node:internal/modules/cjs/loader:1155:14)
    at Object.Module._extensions..js (node:internal/modules/cjs/loader:1209:10)
    at Module.load (node:internal/modules/cjs/loader:1033:32)
    at Function.Module._load (node:internal/modules/cjs/loader:868:12)
    at Function.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:81:12)
    at node:internal/main/run_main_module:22:47
C:\coding-work\github-codeowners\dist\lib\ownership\OwnershipEngine.js:56
            throw error;
            ^

Error:  is not a valid owner name in rule * @snyk/arch
    at createMatcherCodeownersRule (C:\coding-work\github-codeowners\dist\lib\ownership\OwnershipEngine.js:72:23)
    at Function.FromCodeownersFile (C:\coding-work\github-codeowners\dist\lib\ownership\OwnershipEngine.js:50:28)
    at Object.<anonymous> (C:\coding-work\github-codeowners\test.js:3:42)
    at Module._compile (node:internal/modules/cjs/loader:1155:14)
    at Object.Module._extensions..js (node:internal/modules/cjs/loader:1209:10)
    at Module.load (node:internal/modules/cjs/loader:1033:32)
    at Function.Module._load (node:internal/modules/cjs/loader:868:12)
    at Function.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:81:12)
    at node:internal/main/run_main_module:22:47

Expected Output

C:\coding-work\github-codeowners>node test     
[ '@snyk/arch' ]