virtual-code-owners 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2022-2022 Sander Verweij
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,119 @@
+## What?
+
+This takes a
+
+- VIRTUAL-CODEOWNERS.txt file with (virtual) teams
+- a `virtual-teams.yml` file which define the teams
+
+... and churns out a CODEOWNERS with user names.
+
+## Usage
+
+- Rename your `CODEOWNERS` to `VIRTUAL-CODEOWNERS.txt` and put team names in them.
+- Specify team names that don't (yet) exist on GitHub level in a `virtual-teams.yml`
+- Run this:
+
+```
+npx virtual-code-owners VIRTUAL-CODEOWNERS.txt virtual-teams.yml > .github/CODEOWNERS
+```
+
+## Why?
+
+Organizations sometimes have large mono repositories with loads of code owners.
+They or their bureaucracy haven't landed on actually using GitHub teams to clearly
+demarcate that. Teams in those organizations who want to have clear code ownership
+have the following choices:
+
+- Wrestle the bureaucracy.  
+  This is the recommended approach. It might take a while, though - and even
+  though there are good people on many levels in bureaucracies, it might
+  eventually not pan out because #reasons.
+- Maintain a CODEOWNERS file with code assigned to large lists of individuals.  
+  An option, but laborious to maintain.
+- Use `virtual-code-owners`.
+
+## Formats
+
+### VIRTUAL-CODEOWNERS.txt
+
+`VIRTUAL_CODEOWNERS.txt` is a regular, valid GitHub [CODEOWNERS](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners#codeowners-and-branch-protection) file.
+The only difference between VIRTUAL-CODEOWNERS and a CODEOWNERS file is that
+the _teams_ the former uses might not exist yet, except in a `virtual-teams.yml`.
+
+Example:
+
+```
+* @cloud-heroes-all
+.github/ @ch/transversal
+apps/broker @ch/transversal
+apps/ux-portal/ @ch/ux @ch/transversal
+libs/ubc-sales/ @ch/sales
+libs/ubc-after-sales/ @ch/after-sales
+libs/ubc-pre-sales/ @ch/pre-sales
+libs/components/ @ch/ux
+```
+
+### virtual-teams.yml
+
+A valid YAML file that contains a list of teams, with for each team its members:
+
+```yaml
+ch/after-sales:
+  - john-doe-ch
+  - pete-peterson-ch
+  - william-the-fourth-ch
+ch/sales:
+  - gregory-gregson-ch
+  - jane-doe-ch
+ch/pre-sales:
+  - jean-claude-ch
+  - valerie-valerton-ch
+  - averel-dalton-ch
+ch/ux:
+  - davy-davidson-ch
+  - john-johnson-ch
+  - joe-dalton-ch
+ch/transversal:
+  - luke-the-lucky-ch
+# etc
+```
+
+## FAQ
+
+### Can I mix real and virtual teams in `VIRTUAL-CODEOWNERS.txt`?
+
+Yes.
+
+It might be you already have a team or two defined, but just want to use
+_additional_ teams. In that case just don't specify the already-defined teams
+in `virtual-teams.yml` and _virtual-code-owners_ will leave them alone.
+
+### Can I still use usernames in `VIRTUAL-CODEOWNERS.txt`
+
+Yes.
+
+Just make sure there's no name clashes between the username and a (virtual)
+team name and _virtual-code-owners_ will leave the real name alone.
+
+### Any limitations I should know of?
+
+- Currently only works for _usernames_ to identify team members - not for e-mail
+  addresses.
+- If people are in more than one team, chances are they get mentioned multiple
+  times on the same line if both teams are code owners of the same part of the
+  code. While maybe not _looking_ ideal, the resulting code owners file is still
+  valid & ready to rock'n roll.
+- _virtual-code-owners_ assumes the VIRTUAL-CODEOWNERS.txt is a valid CODEOWNERS
+  file and the virtual-teams.yml is a valid yaml file with teams names as keys
+  and team members as arrays under these. It will likely throw errors when this
+  assumption is not met, but the error-messages might not be as clear as possible.
+
+### Why the `.txt` extension?
+
+Various editors assume an ALL_CAPS file name with `#` characters on various lines
+to be markdown, and will auto format them as such - making for either very ugly
+or in worst cases invalid CODOWNERS files. Usually such autoformatting is not
+present on text files.
+
+Apparently these editors know about CODEOWNERS, though so this auto formatting
+doesn't seem to be happening over there.

package/dist/cli.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { program } from "commander";
+import { VERSION } from "./version.js";
+import { readAndConvert } from "./read-and-convert.js";
+program
+    .description("Takes a VIRTUAL-CODEOWNERS.txt & a virtual-teams.yml and emits a CODEOWNERS to stdout")
+    .version(VERSION)
+    .arguments("<virtual-code-owners-file> <virtual-teams.yml>")
+    .parse(process.argv);
+try {
+    console.log(readAndConvert(program.args[0], program.args[1]));
+}
+catch (pError) {
+    console.error(`ERROR: ${pError.message}`);
+}

package/dist/convert-virtual-code-owners.js

@@ -0,0 +1,33 @@
+import { EOL } from "node:os";
+const DEFAULT_GENERATED_WARNING = `#${EOL}` +
+    `# DO NOT EDIT - this file is generated and your edits will be overwritten${EOL}` +
+    `#${EOL}` +
+    `# To make changes:${EOL}` +
+    `#${EOL}` +
+    `#   - edit VIRTUAL-CODEOWNERS.txt${EOL}` +
+    `#   - run 'npx virtual-code-owners VIRTUAL-CODE-OWNERS.txt virtual-teams.yml > CODEOWNERS'${EOL}` +
+    `#${EOL}${EOL}`;
+function replaceTeamNames(pLine, pTeamMap) {
+    let lReturnValue = pLine;
+    for (let lTeamName of Object.keys(pTeamMap)) {
+        lReturnValue = lReturnValue.replace(`@${lTeamName}`, pTeamMap[lTeamName].map((pUserName) => `@${pUserName}`).join(" "));
+    }
+    return lReturnValue;
+}
+function convertLine(pTeamMap) {
+    return (pUntreatedLine) => {
+        const lTrimmedLine = pUntreatedLine.trimStart();
+        if (lTrimmedLine.startsWith("#") || lTrimmedLine === "") {
+            return pUntreatedLine;
+        }
+        else {
+            return replaceTeamNames(pUntreatedLine, pTeamMap);
+        }
+    };
+}
+export function convert(pCodeOwnersFileAsString, pTeamMap, pGeneratedWarning = DEFAULT_GENERATED_WARNING) {
+    return `${pGeneratedWarning}${pCodeOwnersFileAsString
+        .split(EOL)
+        .map(convertLine(pTeamMap))
+        .join(EOL)}`;
+}

package/dist/read-and-convert.js

@@ -0,0 +1,13 @@
+import { readFileSync } from "node:fs";
+import yaml from "js-yaml";
+import { convert } from "./convert-virtual-code-owners.js";
+export function readAndConvert(pVirtualCodeOwnersFileName, pVirtualTeamsFileName) {
+    const lVirtualCodeOwnersFileAsAString = readFileSync(pVirtualCodeOwnersFileName, {
+        encoding: "utf-8",
+    });
+    const lVirtualTeamsYamlAsAString = readFileSync(pVirtualTeamsFileName, {
+        encoding: "utf-8",
+    });
+    const lTeamMap = yaml.load(lVirtualTeamsYamlAsAString);
+    return convert(lVirtualCodeOwnersFileAsAString, lTeamMap);
+}

package/dist/version.js

@@ -0,0 +1 @@
+export const VERSION = "1.0.0";

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "virtual-code-owners",
+  "version": "1.0.0",
+  "description": "merges a VIRTUAL-CODEOWNERS.txt and a virtual-teams.yml into CODEOWNERS",
+  "type": "module",
+  "exports": {
+    ".": [
+      {
+        "import": "./dist/read-and-convert.js"
+      },
+      "./dist/read-and-convert.js"
+    ]
+  },
+  "main": "dist/read-and-convert.js",
+  "bin": "dist/cli.js",
+  "files": [
+    "dist",
+    "package.json",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && node tools/get-version.mjs > src/version.ts && tsc",
+    "depcruise": "depcruise src --config .dependency-cruiser.cjs",
+    "depcruise:graph": "depcruise src --include-only '^(src)' --config --output-type dot | dot -T svg | depcruise-wrap-stream-in-html > dependency-graph.html",
+    "depcruise:graph:dev": "depcruise src --prefix vscode://file/$(pwd)/ --config --output-type dot | dot -T svg | depcruise-wrap-stream-in-html | browser",
+    "depcruise:graph:diff:dev": "depcruise src --prefix vscode://file/$(pwd)/ --config --output-type dot --reaches \"$(watskeburt $SHA -T regex)\"| dot -T svg | depcruise-wrap-stream-in-html | browser",
+    "depcruise:graph:diff:mermaid": "depcruise src --config --output-type mermaid --output-to - --reaches \"$(watskeburt $SHA -T regex)\"",
+    "depcruise:html": "depcruise src --config --output-type err-html --output-to dependency-violation-report.html",
+    "format": "prettier --loglevel warn --write \"**/*.{md,ts,json,yml}\"",
+    "scm:stage": "git add .",
+    "test": "NODE_OPTIONS=--no-warnings mocha",
+    "test:cover": "NODE_OPTIONS=--no-warnings c8 mocha",
+    "update-dependencies": "npm run upem:update && npm run upem:install && npm run format && npm run build && npm test",
+    "upem-outdated": "npm outdated --json --long | upem --dry-run",
+    "upem:install": "npm install",
+    "upem:update": "npm outdated --json --long | upem | pbcopy && pbpaste",
+    "version": "npm run build && npm run scm:stage"
+  },
+  "keywords": [
+    "CODEOWNERS"
+  ],
+  "author": "Sander Verweij (https://sverweij.github.io/)",
+  "license": "MIT",
+  "homepage": "https://github.com/sverweij/virtual-code-owners",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sverweij/virtual-code-owners"
+  },
+  "bugs": {
+    "url": "https://github.com/sverweij/virtual-code-owners/issues"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "4.0.5",
+    "@types/node": "18.14.5",
+    "c8": "7.13.0",
+    "dependency-cruiser": "12.10.0",
+    "mocha": "10.2.0",
+    "prettier": "2.8.4",
+    "ts-node": "10.9.1",
+    "typescript": "4.9.5",
+    "upem": "7.3.2",
+    "watskeburt": "0.10.0"
+  },
+  "dependencies": {
+    "commander": "10.0.0",
+    "js-yaml": "4.1.0"
+  },
+  "engines": {
+    "node": "^14.13.1||^16||>=18"
+  }
+}