# @nmann/codeowners

> A tool for working with CODEOWNERS files

Latest version **2.1.1** (published 2025-08-26) · MIT license · 0 weekly downloads

## Install

```sh
npm install @nmann/codeowners
pnpm add @nmann/codeowners
yarn add @nmann/codeowners
bun add @nmann/codeowners
```

Provides the command `codeowners`.

## Health

**Score 60/100 (C)** — status: stable.

Positive: has types; esm support; no vulnerabilities; has provenance; high maintenance score; high quality score.

Warnings: low downloads.

Negative: stale.

## Facts

| | |
|---|---|
| Version | 2.1.1 |
| Published | 2025-08-26 |
| First published | 2022-09-26 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=16.10.0 |
| Dependencies | 5 |
| Unpacked size | 23.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 4 |
| Maintainers | noahmann |
| Keywords | codeowners, github, gitlab |

## Links

- npm: https://www.npmjs.com/package/@nmann/codeowners
- Repository: https://github.com/noahm/codeowners
- Homepage: https://github.com/noahm/codeowners#readme
- Issues: https://github.com/noahm/codeowners/issues
- npm.io page: https://npm.io/package/@nmann/codeowners

## Dependencies (5)

- [ignore](https://npm.io/package/ignore.md) ^5.0.0
- [find-up](https://npm.io/package/find-up.md) ^7.0.0
- [commander](https://npm.io/package/commander.md) ^12.0.0
- [true-case-path](https://npm.io/package/true-case-path.md) ^2.0.0
- [@nodelib/fs.walk](https://npm.io/package/@nodelib/fs.walk.md) ^2.0.0

## Recent versions

- 2.1.1 (latest) — 2025-08-26
- 3.0.0-alpha.1 (next) — 2025-12-13
- 3.0.0-alpha.0 — 2025-12-13
- 2.1.1-alpha.1 — 2025-08-25
- 2.1.0 — 2024-09-19
- 2.0.2 — 2024-01-29
- 2.0.1 — 2023-09-15
- 2.0.0 — 2023-09-15
- 1.0.0 — 2022-09-26

## README

# @nmann/codeowners

[![npm](https://img.shields.io/npm/v/@nmann/codeowners)](https://www.npmjs.com/package/@nmann/codeowners)

A library and CLI for interacting with GitHub's
[CODEOWNERS](https://help.github.com/articles/about-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](https://marketplace.visualstudio.com/items?itemName=noahm.codeowners-extended).

## Library usage

```js
const Codeowners = require('@nmann/codeowners');

// defaults to process.cwd(), but can pass a different directory path to constructor
const owners = new Codeowners();
owners.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:

```sh
## team slack-channel engineering-manager jira-project-key
## @org/admins #project-admins @alice ADMIN
## @org/design #design @bob DESIGN
## @org/monetization #monetization-eng @charlie MONEY

# ... 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:

```js
[
  {
    team: '@org/admins',
    'slack-channel': '#project-admins',
    'engineering-manager': '@alice',
    'jira-project-key': 'ADMIN',
  },
  {
    team: '@org/design',
    'slack-channel': '#design',
    'engineering-manager': '@bob',
    'jira-project-key': 'DESIGN',
  },
  {
    team: '@org/monetization',
    'slack-channel': '#monetization-eng',
    'engineering-manager': '@charlie',
    'jira-project-key': 'MONEY',
  },
];
```

## CLI usage

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

```sh
$ codeowners of some/file.ts [...otherfiles]
```

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

```sh
$ codeowners audit
```

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

```sh
$ codeowners audit --unowned
```

Specify a non-standard CODEOWNERS filename

```sh
$ codeowners audit -c CODEKEEPERS
```

Verify users/teams own a specific path

```sh
$ codeowners verify src/ @foob_ar @contoso/engineers
```

---
_Source: https://npm.io/package/@nmann/codeowners · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._