@nmann/codeowners

A library and CLI for interacting with GitHub's CODEOWNERS files.

It extends GitHubs's file format to to use the CODEOWNERS file as a source of truth for metadata about teams. This is useful for quick reference to things like preferred contact channels, JIRA project names, etc.

This metadata can be made even easier to access with a companion VS Code extension.

Library usage

1const Codeowners = require('@nmann/codeowners');
2
3// defaults to process.cwd(), but can pass a different directory path to constructor
4const owners = new Codeowners();
5owners.getOwner('path/to/file.js'); // returns array of one or more owners, e.g. ['@noahm']

Team metadata

This library will attempt to parse out contact info for teams if listed in a simple space-separated-values format. Only lines beginning with a double-pound "##" will be parsed.

The first line is a space-separated list of column names, and the following lines provide values for those columns, one line per team.

Example team metadata block:

1## team slack-channel engineering-manager jira-project-key
2## @org/admins #project-admins @alice ADMIN
3## @org/design #design @bob DESIGN
4## @org/monetization #monetization-eng @charlie MONEY
5
6# ... regular codeowners file contents ...

This info is parsed and made available in an array of structured objects on the contactInfo field of a codeowners class instance:

1[
2  {
3    team: '@org/admins',
4    'slack-channel': '#project-admins',
5    'engineering-manager': '@alice',
6    'jira-project-key': 'ADMIN',
7  },
8  {
9    team: '@org/design',
10    'slack-channel': '#design',
11    'engineering-manager': '@bob',
12    'jira-project-key': 'DESIGN',
13  },
14  {
15    team: '@org/monetization',
16    'slack-channel': '#monetization-eng',
17    'engineering-manager': '@charlie',
18    'jira-project-key': 'MONEY',
19  },
20];

CLI usage

Find the owner(s) of a given file or files:

1$ codeowners of some/file.ts [...otherfiles]

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

1$ codeowners audit

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

1$ codeowners audit --unowned

Specify a non-standard CODEOWNERS filename

1$ codeowners audit -c CODEKEEPERS

Verify users/teams own a specific path

1$ codeowners verify src/ @foob_ar @contoso/engineers