raulfdm / codeowners-flow

A tool to script and manage the CODEOWNERS file programmatically, simplifying code ownership rules and generating platform-compatible files.

codeowners-flow

Programmatically manage your CODEOWNERS file.

About

Version control platforms (e.g., GitHub, Azure, GitLab, etc.) utilize the CODEOWNERS strategy to specify which parts of a repository are owned by particular teams or individuals. This becomes incredibly useful for notifying the appropriate owners in Pull Requests when their code undergoes modifications.

The CODEOWNERS file follows its own distinct syntax:

• Lines starting with # are treated as comments.
• The format is <pattern> <team|user>, where:
  • <pattern> allows the platform to "match" the files (e.g., * for everything, apps/backend matches the backend folder inside apps, etc.).
  • <team|user> is a list of teams or users that own that section of code. Multiple teams or users are separated by space.

For example:

# Fallback maintainers
* @company/core-team

# Backend core
apps/backend @company/backend-core

# Backend API
apps/backend-endpoint @company/microservices @company/backend-core

Issues emerge when multiple teams work within a single codebase and there's a necessity to delineate precise ownership among them.

Consider a scenario where you want to designate a "default team ownership" on of the other owners. For each rule, one would have to not only designate the specific owner for that code but also the default team. This configuration might look like:

* @company/core-team

apps/backend @company/backend-core @company/core-team

apps/front-end @company/web-core @company/core-team

packages/analytics @company/data-analytics @company/core-team

In this example, we manually appended @company/core-team to each CODEOWNERS match pattern. If you later decide that multiple teams should be "default maintainers", updating every single entry to include these new teams becomes cumbersome.

The core issue: maintaining a comprehensive CODEOWNERS file can get tedious and prone to errors.

Wouldn't it be beneficial if the CODEOWNERS file could be scripted? What if JavaScript could be used to define these rules, and then generate the corresponding file?

Enter this tool. It provides teams the capability to script code ownership rules via straightforward JavaScript and subsequently outputs a file that's recognized by the platforms.

Usage

For comprehensive instructions, please refer to the CLI README.

License

MIT

codeowners-flow's Issues

add eslint

Define config API

API config

Every project would include a codeowner.config.mjs. This file must default return an array of objects.

Each object should contain:

type OwnerRule = {
  pattern: string,
  excludeMatch?: string[],
  owners: string[],
  comments?: string[]
}

type CodeOwnerManager = {
  outDir: string;
  rules: OwnerRule[]
}

Example:

export default {
  outDir: ".github",
  rules: [
    {
      pattern: "*",
      owners: ["@company/core-team"],
      comments: [
        "Everything else will be fallback to @company/core-team to approve",
      ],
    },
  ],
};

This will lead to a .github/CODEOWNERS with the following content:

# Everything else will be fallback to @company/core-team to approve
* @company/core-team

fix `meow` dependency

it should be listed independencies, not in devDependencies

add option to tweak programmatically the configuration

Description

The user should be allowed to extend the configuration programmatically. This will be handy for automation/scripting.

import { updateConfig, defineRule } from "@codeowners-flow/cli/config";

await updateConfig((currentConfig) => {
  currentConfig.rules = defineRule({
    patterns: ["module/logger"],
    owners: ["@company/infra"],
  });

  return currentConfig;
});

Because the user gets the current config, it might be useful to provide a field like _meta so they can add and maintain info in the config level but also have access, like:

// codeowners.config.mjs

const mainTeam = { name: '@company/core-team' };

/** @type {import('@codeowners-flow/cli/config').UserConfig} */
export default {
  outDir: '.github',
  _meta: {
    mainTeam, // HERE
  },
  rules: [
    {
      patterns: ['*'],
      owners: [mainTeam],
    },
  ],
};

Then:

import { updateConfig, defineRule } from "@codeowners-flow/cli/config";

await updateConfig((currentConfig) => {
  currentConfig.rules = defineRule({
    patterns: ["module/logger"],
    owners: ["@company/infra", currentConfig._meta.mainTeam], // CONSUMING HERE
  });

  return currentConfig;
});

I'm not sure how to make this type-safe, so it'll be the user's responsibility to ensure the value is there.

add website docs

add unit tests

add option to init a project

Add root and package README

Error calling the CLI

Description

After installing the CLI and trying to run, I got:

$ pnpm codeowners-flow     
node:internal/errors:464
    ErrorCaptureStackTrace(err);
    ^

Error [ERR_MODULE_NOT_FOUND]: Cannot find module '/path/to/node_modules/.pnpm/@[email protected]/node_modules/@codeowners-flow/cli/dist/index.js' imported from /path/to/node_modules/.pnpm/@[email protected]/node_modules/@codeowners-flow/cli/bin/index.js
    at new NodeError (node:internal/errors:371:5)
    at finalizeResolution (node:internal/modules/esm/resolve:418:11)
    at moduleResolve (node:internal/modules/esm/resolve:981:10)
    at defaultResolve (node:internal/modules/esm/resolve:1078:11)
    at ESMLoader.resolve (node:internal/modules/esm/loader:530:30)
    at ESMLoader.getModuleJob (node:internal/modules/esm/loader:251:18)
    at ESMLoader.import (node:internal/modules/esm/loader:332:22)
    at importModuleDynamically (node:internal/modules/esm/translators:106:35)
    at importModuleDynamicallyCallback (node:internal/process/esm_loader:35:14)
    at file:///path/to/node_modules/.pnpm/@[email protected]/node_modules/@codeowners-flow/cli/bin/index.js:4:1 {
  code: 'ERR_MODULE_NOT_FOUND'
}

Checking the node_modules, it seems the dist folder isn't there 🫠

convert project to monorepo

In case I want to separate concerns, better to be in a monorepo already

expose typed functions to write config

write CODEOWNERS

add changesets

add CLI parsing

add option to point a config file

add husky, prettier and lint stanged