beaugunderson/codeowners

👁 audit your CODEOWNERS file

codeowners

A tool for interacting with GitHub's CODEOWNERS files.

Usable as a CLI, or as a library.

installation

$ npm install -g codeowners

cli usage

Print a list of each files in the current repo, followed by its owner:

$ codeowners audit

To find a list of files not covered by the CODEOWNERS in the project:

$ codeowners audit --unowned

Specify a non-standard CODEOWNERS filename

$ codeowners audit -c CODEKEEPERS

Verify users/teams own a specific path

$ codeowners verify src/ @foob_ar @contoso/engineers

library usage

const Codeowners = require('codeowners');

// workingDir is optional, defaults to process.cwd()
const repos = new Codeowners(workingDir);
repos.getOwner('path/to/file.js'); // => array of owner strings, e.g. ['@noahm']

CHANGELOG

5.0.0

• Much-improved performance
• Removal of automatic column width calculation
• Addition of -w/--width option for manual column width
  • Or use e.g. codeowners audit | column -ts " "

codeowners's Issues

Exit with non-zero code if there are unowned files

I'd like to use this package to ensure that all files are owned by someone. This check should be part of a CI job. It would be very convenient to have a flag that will have unowned files cause a non-zero exit.

Not filtering node_modules and .git directories

When using version 5.1.0 (and probably previous versions), tool is not filtering node_modules nor .git directories out.

It's related to dependency @nodelib/[email protected], there is no filter option, but deepFilter.

See PR #20

Huge memory consumption when running on large repository with many codeowners rules

I have a large repository, containing ~500 000 files (in a large directory tree). Running codeowners -u on it requires allowing around 8 GB RAM to NodeJS (--max_old_space_size=8000) and I see it increasing as the scan progresses. It's an issue both for running locally an in an automatic pipeline.

I didn't expect filesystem traversal to require linearly increasing memory usage. Is there a reason for it?

Feature request: list the owners of the specified file

$ codeowners of path/to/some/file

Provide hook for using this library with pre-commit

pre-commit is a popular framework for running Git hooks before commits or pushes. To make a library work with pre-commit, it must provide hooks.

This will make it easier to use this library as a part of most developers' local setups and CI, especially with #8.

Reference

• https://github.com/pre-commit/mirrors-eslint
• Documentation for creating new hooks

Support Default Owners

Currently doesn't recognize default owners as prescribed in gitlab's documentation.

https://docs.gitlab.com/ee/user/project/codeowners/#set-default-owner-for-a-section

Feature: API for generating codeowners files

Hi!

I've recently been working on a project where I programmatically generate the codeowners file based on some configuration. So far, I've written a fairly simple class that gives an API to describe a codeowners file (rules, comments, and newlines), and I'm wondering if you'd like this contributed back?

I'm thinking more along the lines of parsing a CODEOWNERS file to a simple AST (see below), and then set of methods to work with that AST and a means to convert the AST to a CODEOWNERS file.

Example AST:

{
  type: 'rule' | 'comment' | 'newline'
  // For type == comment
  message?: string
  // For type == rule
  pattern: string
  owners: string[]
}

The Codeowners function would then change to:

// If options.read == true, then call Codeowners.prototype.readSync() followed by Codeowners.prototype.parse()
// options.read will default to true, as this closest resembles the existing behaviour
new Codeowners(currentPath, fileName = 'CODEOWNERS', options?: { read: true })
Codeowners.prototype.getOwner(filepath: string);

Codeowners.prototype.parse() // called by constructor

Codeowners.prototype.addComment(message?: string)
Codeowners.prototype.addRule(pattern: string, owners: string[])
Codeowners.prototype.addNewline()

Codeowners.prototype.toString() // output the current AST as a CODEOWNERS file

async Codeowners.prototype.read()
async Codeowners.prototype.write()

Codeowners.prototype.readSync()
Codeowners.prototype.writeSync()

Thoughts? This would allow programmatic management of CODEOWNERS files, we could also optionally do a breaking API change of:

new Codeowners(filepath: string, options?: { read: true });

Codeowners.discover(currentPath: string, filename = 'CODEOWNERS')

Such that existing code using the API would be:

- const owners = new Codeowners(workingDir);
+ const ownersFile = Codeowners.discover(workingDir);
+ const owners = new Codeowners(ownersFile, options?: { read: true });

Invalid codeowners should be filtered out

e.g. if a file has a codeowners like:

a/** cool-team # TODO: change

this library spits out 4 code owners: cool-team, #, TODO: and change. While nothing can be done for change at least # is a known invalid codeowner

Incorrectly implements rules for nested matches

I recently discovered that the CODEOWNERS format isn't exactly the same as gitignore; it's similar but has a difference in the handling of foo/* vs foo/ — the former only matches files and directories that are direct descendants, so foo/baz.c and foo/bar/ would match, but foo/bar/baz.c would not.

This is based on the logic described in their example:

# In this example, @doctocat owns any files in the build/logs
# directory at the root of the repository and any of its
# subdirectories.
/build/logs/ @doctocat

# The `docs/*` pattern will match files like
# `docs/getting-started.md` but not further nested files like
# `docs/build-app/troubleshooting.md`.
docs/*  [email protected]

There's a similar issue in this package: hmarr/codeowners#2

Audit reports on files that aren't tracked by git

When using the audit feature, untracked files (e.g. files that are generated by a build process and aren't tracked by git) are reported on. I think this code that finds candidate files should be powered by something equivalent to git ls-files.

I may be able to contribute a PR if you think this change makes sense. Let me know.

Can't execute with `npx run codeowners`

I wanted to try out this tool without actively installing it into any environment, so I tried npx run codeowners and got this error:

$ npx run codeowners audit
npx: installed 5 in 1.536s
Watching /Users/<REDACTED> and all sub-directories not excluded by your .gitignore. Will not monitor dotfiles.
Found & ignored ./.cache ; is listed in .gitignore
Found & ignored ./.circleci ; is listed in .gitignore
...

Starting: codeowners audit
internal/modules/cjs/loader.js:638
    throw err;
    ^

Error: Cannot find module '/Users/<REDACTED>/codeowners'
    at Function.Module._resolveFilename (internal/modules/cjs/loader.js:636:15)
    at Function.Module._load (internal/modules/cjs/loader.js:562:25)
    at Function.Module.runMain (internal/modules/cjs/loader.js:831:12)
    at startup (internal/bootstrap/node.js:283:19)
    at bootstrapNodeJSCore (internal/bootstrap/node.js:623:3)
^C

Using npm install -g codeowners worked fine, but wanted to point this out in case there's others trying out the tool.

Does not support Windows paths

Support CODEOWNERS file under /.github or /docs directory

See https://help.github.com/articles/about-codeowners/#codeowners-file-location

Feature Request: Flag to ignore files in .gitignore

A great feature would be having the option to filter out all the files that are included in the .gitignore.

Something like:

codeowners audit --unowned --no-ignored

Handle broken symlinks

Currently we fail if there's a broken symlink somewhere in under the CWD.