virtual-code-owners 4.1.1 → 5.1.0

package/README.md

@@ -167,6 +167,23 @@ 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.
 
+### What validations does virtual-code-owners perform?
+
+On the VIRTUAL-CODEOWNERS.txt file it performs is a little bit of validation:
+
+- it will find invalid user/ team names (those that don't start with an `@` or
+  aren't an e-mail address)
+- it will find invalid 'rules'; which is the case when there is a file pattern on
+  the line, but no user or team names.
+
+When it encounters any of these virtual-code-owners will emit a clear error message
+with the location of the error and exit with a non-zero code, to prevent the
+creation of a potentially invalid CODEOWNERS file.
+
+It _does not_ check whether the user or team names actually exist in the current
+project, though. Although nice, there's already tooling on the generated CODEOWNERS
+file that will check that for you.
+
 ### Any limitations I should know of?
 
 - ~~Currently only works for _user names_ to identify team members - not for e-mail
@@ -202,3 +219,20 @@ like this:
   ]
 }
 ```
+
+### It'd be _pretty_ handy if I could see for which virtual teams a PR is. For instance with a bunch of :label: labels.
+
+How do I go about that?
+
+You can use the [actions/labeler](https://github.com/actions/labeler) action for
+for this. Maintaining the configuration file (`.github/labeler.yml`) and keeping it
+sync with the virtual-teams and virtual code-owners files manually is a bit of
+a chore, though, so `virtual-code-owners` has an option to automate that.
+
+```sh
+npx virtual-code-owners --emitLabeler
+# Wrote .github/CODEOWNERS AND .github/labeler.yml
+```
+
+If you have an alternate file location for the `labeler.yml` you can specify that
+with virtual-code-owner's `--labelerLocation` parameter.

package/dist/generate-codeowners.js

@@ -0,0 +1,46 @@
+import { EOL } from "node:os";
+import { isEmailIshUsername } from "./utensils.js";
+const DEFAULT_WARNING = `#${EOL}` +
+    `# DO NOT EDIT - this file is generated and your edits will be overwritten${EOL}` +
+    `#${EOL}` +
+    `# To make changes:${EOL}` +
+    `#${EOL}` +
+    `#   - edit .github/VIRTUAL-CODEOWNERS.txt${EOL}` +
+    `#   - and/ or add team members to .github/virtual-teams.yml${EOL}` +
+    `#   - run 'npx virtual-code-owners' (or 'npx virtual-code-owners --emitLabeler' if you also${EOL}` +
+    `#     want to generate a .github/labeler.yml)${EOL}` +
+    `#${EOL}${EOL}`;
+export default function generateCodeOwners(pVirtualCodeOwners, pTeamMap, pGeneratedWarning = DEFAULT_WARNING) {
+    return (pGeneratedWarning +
+        pVirtualCodeOwners
+            .filter((pLine) => pLine.type !== "ignorable-comment")
+            .map((pLine) => generateLine(pLine, pTeamMap))
+            .join(EOL));
+}
+function generateLine(pCSTLine, pTeamMap) {
+    if (pCSTLine.type === "rule") {
+        const lUserNames = uniq(pCSTLine.users.flatMap((pUser) => expandTeamToUserNames(pUser, pTeamMap)))
+            .sort()
+            .join(" ");
+        return pCSTLine.filesPattern + pCSTLine.spaces + lUserNames;
+    }
+    return pCSTLine.raw;
+}
+function expandTeamToUserNames(pUser, pTeamMap) {
+    if (pUser.type == "virtual-team-name") {
+        return stringifyTeamMembers(pTeamMap, pUser.bareName);
+    }
+    return [pUser.raw];
+}
+function stringifyTeamMembers(pTeamMap, pTeamName) {
+    return pTeamMap[pTeamName].map(userNameToCodeOwner);
+}
+function userNameToCodeOwner(pUserName) {
+    if (isEmailIshUsername(pUserName)) {
+        return pUserName;
+    }
+    return `@${pUserName}`;
+}
+function uniq(pUserNames) {
+    return Array.from(new Set(pUserNames));
+}

package/dist/generate-labeler-yml.js

@@ -0,0 +1,47 @@
+import { EOL } from "node:os";
+const DEFAULT_WARNING = `#${EOL}` +
+    `# DO NOT EDIT - this file is generated and your edits will be overwritten${EOL}` +
+    `#${EOL}` +
+    `# To make changes:${EOL}` +
+    `#${EOL}` +
+    `#   - edit .github/VIRTUAL-CODEOWNERS.txt${EOL}` +
+    `#   - and/ or add teams (& members) to .github/virtual-teams.yml${EOL}` +
+    `#   - run 'npx virtual-code-owners --emitLabeler'${EOL}` +
+    `#${EOL}${EOL}`;
+export default function generateLabelerYml(pCodeOwners, pTeamMap, pGeneratedWarning = DEFAULT_WARNING) {
+    let lReturnValue = pGeneratedWarning;
+    for (const lTeamName in pTeamMap) {
+        const lPatternsForTeam = getPatternsForTeam(pCodeOwners, lTeamName)
+            .map((pPattern) => `  - ${transformForYamlAndMinimatch(pPattern)}${EOL}`)
+            .join("");
+        if (lPatternsForTeam) {
+            lReturnValue += `${lTeamName}:${EOL}${lPatternsForTeam}${EOL}`;
+        }
+    }
+    return lReturnValue;
+}
+function getPatternsForTeam(pCodeOwners, pTeamName) {
+    return (pCodeOwners
+        .filter((pLine) => {
+        const isARule = pLine.type === "rule";
+        return (isARule &&
+            lineContainsTeamName(pLine, pTeamName));
+    })
+        .map((pLine) => pLine.filesPattern));
+}
+function transformForYamlAndMinimatch(pOriginalString) {
+    let lReturnValue = pOriginalString;
+    if (pOriginalString === "*") {
+        lReturnValue = "**";
+    }
+    if (lReturnValue.startsWith("*")) {
+        lReturnValue = `'${lReturnValue}'`;
+    }
+    if (pOriginalString.endsWith("/")) {
+        lReturnValue = `${lReturnValue}**`;
+    }
+    return lReturnValue;
+}
+function lineContainsTeamName(pLine, pTeamName) {
+    return pLine.users.some((pUser) => pUser.type === "virtual-team-name" && pUser.bareName === pTeamName);
+}

package/dist/main.js

@@ -1,8 +1,12 @@
-import { VERSION } from "./version.js";
-import { readAndConvert } from "./read-and-convert.js";
 import { writeFileSync } from "node:fs";
 import { EOL } from "node:os";
 import { parseArgs } from "node:util";
+import generateCodeOwners from "./generate-codeowners.js";
+import generateLabelerYml from "./generate-labeler-yml.js";
+import readTeamMap from "./read-team-map.js";
+import readVirtualCodeOwners from "./read-virtual-code-owners.js";
+import { VERSION } from "./version.js";
+import { getAnomalies } from "./parse.js";
 const HELP_MESSAGE = `Usage: virtual-code-owners [options]
 
 Merges a VIRTUAL-CODEOWNERS.txt and a virtual-teams.yml into CODEOWNERS
@@ -17,10 +21,15 @@ Options:
                                        (default: ".github/virtual-teams.yml")
   -c, --codeOwners [file-name]         The location of the CODEOWNERS file 
                                        (default: ".github/CODEOWNERS")
+  -l, --emitLabeler                    Whether or not to emit a labeler.yml to be
+                                       used with actions/labeler
+                                       (default: false)
+  --labelerLocation [file-name]        The location of the labeler.yml file
+                                       (default: ".github/labeler.yml")
   -h, --help                           display help for command`;
 export function main(pArguments = process.argv.slice(2), pOutStream = process.stdout, pErrorStream = process.stderr) {
     try {
-        let lOptions = getOptions(pArguments);
+        const lOptions = getOptions(pArguments);
         if (lOptions.help) {
             pOutStream.write(`${HELP_MESSAGE}${EOL}`);
             return;
@@ -29,17 +38,45 @@ export function main(pArguments = process.argv.slice(2), pOutStream = process.st
             pOutStream.write(`${VERSION}${EOL}`);
             return;
         }
-        const lCodeOwnersContent = readAndConvert(lOptions.virtualCodeOwners, lOptions.virtualTeams);
+        const lTeamMap = readTeamMap(lOptions.virtualTeams);
+        const lVirtualCodeOwners = readVirtualCodeOwners(lOptions.virtualCodeOwners, lTeamMap);
+        const lAnomalies = getAnomalies(lVirtualCodeOwners);
+        if (lAnomalies.length > 0) {
+            throw new Error(`${EOL}${reportAnomalies(lOptions.virtualCodeOwners, lAnomalies)}`);
+        }
+        const lCodeOwnersContent = generateCodeOwners(lVirtualCodeOwners, lTeamMap);
         writeFileSync(lOptions.codeOwners, lCodeOwnersContent, {
             encoding: "utf-8",
         });
-        pErrorStream.write(`${EOL}Wrote ${lOptions.codeOwners}${EOL}${EOL}`);
+        if (lOptions.emitLabeler) {
+            const lLabelerContent = generateLabelerYml(lVirtualCodeOwners, lTeamMap);
+            writeFileSync(lOptions.labelerLocation, lLabelerContent, {
+                encoding: "utf-8",
+            });
+            pErrorStream.write(`${EOL}Wrote ${lOptions.codeOwners} AND ${lOptions.labelerLocation}${EOL}${EOL}`);
+        }
+        else {
+            pErrorStream.write(`${EOL}Wrote ${lOptions.codeOwners}${EOL}${EOL}`);
+        }
     }
     catch (pError) {
         pErrorStream.write(`${EOL}ERROR: ${pError.message}${EOL}${EOL}`);
         process.exitCode = 1;
     }
 }
+function reportAnomalies(pFileName, pAnomalies) {
+    return pAnomalies
+        .map((pAnomaly) => {
+        if (pAnomaly.type === "invalid-line") {
+            return `${pFileName}:${pAnomaly.line}:1 invalid line - neither a rule, comment nor empty: '${pAnomaly.raw}'`;
+        }
+        else {
+            return (`${pFileName}:${pAnomaly.line}:1 invalid user or team name '${pAnomaly.raw}' (# ${pAnomaly.userNumberWithinLine} on this line). ` +
+                `It should either start with '@' or be an e-mail address.`);
+        }
+    })
+        .join(EOL);
+}
 function getOptions(pArguments) {
     return parseArgs({
         args: pArguments,
@@ -59,6 +96,15 @@ function getOptions(pArguments) {
                 short: "c",
                 default: ".github/CODEOWNERS",
             },
+            emitLabeler: {
+                type: "boolean",
+                short: "l",
+                default: false,
+            },
+            labelerLocation: {
+                type: "string",
+                default: ".github/labeler.yml",
+            },
             help: { type: "boolean", short: "h", default: false },
             version: { type: "boolean", short: "V", default: false },
         },

package/dist/parse.js

@@ -0,0 +1,92 @@
+import { EOL } from "node:os";
+import { isEmailIshUsername } from "./utensils.js";
+export function parse(pVirtualCodeOwnersAsString, pTeamMap = {}) {
+    return pVirtualCodeOwnersAsString
+        .split(EOL)
+        .map((pUntreatedLine, pLineNo) => parseLine(pUntreatedLine, pTeamMap, pLineNo + 1));
+}
+export function getAnomalies(pVirtualCodeOwners) {
+    const weirdLines = pVirtualCodeOwners
+        .filter((pLine) => pLine.type === "unknown")
+        .map((pLine) => ({
+        ...pLine,
+        type: "invalid-line",
+    }));
+    const weirdUsers = pVirtualCodeOwners.flatMap((pLine) => {
+        if (pLine.type === "rule") {
+            return pLine.users
+                .filter((pUser) => pUser.type === "invalid")
+                .map((pUser) => ({
+                ...pUser,
+                line: pLine.line,
+                type: "invalid-user",
+            }));
+        }
+        return [];
+    });
+    return weirdLines.concat(weirdUsers).sort(orderAnomaly);
+}
+function orderAnomaly(pLeft, pRight) {
+    if (pLeft.line === pRight.line &&
+        pLeft.type === "invalid-user" &&
+        pRight.type === "invalid-user") {
+        return pLeft.userNumberWithinLine > pRight.userNumberWithinLine ? 1 : -1;
+    }
+    else {
+        return pLeft.line > pRight.line ? 1 : -1;
+    }
+}
+function parseLine(pUntreatedLine, pTeamMap, pLineNo) {
+    const lTrimmedLine = pUntreatedLine.trim();
+    const lSplitLine = lTrimmedLine.match(/^(?<filesPattern>[^\s]+)(?<spaces>\s+)(?<userNames>.*)$/);
+    if (lTrimmedLine.startsWith("#!")) {
+        return { type: "ignorable-comment", line: pLineNo, raw: pUntreatedLine };
+    }
+    if (lTrimmedLine.startsWith("#")) {
+        return { type: "comment", line: pLineNo, raw: pUntreatedLine };
+    }
+    if (!lSplitLine?.groups) {
+        if (lTrimmedLine === "") {
+            return { type: "empty", line: pLineNo, raw: pUntreatedLine };
+        }
+        return { type: "unknown", line: pLineNo, raw: pUntreatedLine };
+    }
+    return {
+        type: "rule",
+        line: pLineNo,
+        filesPattern: lSplitLine.groups.filesPattern,
+        spaces: lSplitLine.groups.spaces,
+        users: parseUsers(lSplitLine.groups.userNames, pTeamMap),
+        raw: pUntreatedLine,
+    };
+}
+function parseUsers(pUserNamesString, pTeamMap) {
+    const lUserNames = pUserNamesString.split(/\s+/);
+    return lUserNames.map((pUserName, pIndex) => {
+        const lBareName = getBareUserName(pUserName);
+        return {
+            type: getUserNameType(pUserName, lBareName, pTeamMap),
+            userNumberWithinLine: pIndex + 1,
+            bareName: lBareName,
+            raw: pUserName,
+        };
+    });
+}
+function getUserNameType(pUserName, pBareName, pTeamMap) {
+    if (isEmailIshUsername(pUserName)) {
+        return "e-mail-address";
+    }
+    if (pUserName.startsWith("@")) {
+        if (pTeamMap.hasOwnProperty(pBareName)) {
+            return "virtual-team-name";
+        }
+        return "other-user-or-team";
+    }
+    return "invalid";
+}
+function getBareUserName(pUserName) {
+    if (pUserName.startsWith("@")) {
+        return pUserName.slice(1);
+    }
+    return pUserName;
+}

package/dist/read-team-map.js

@@ -0,0 +1,8 @@
+import { readFileSync } from "node:fs";
+import { parse as parseYaml } from "yaml";
+export default function readTeamMap(pVirtualTeamsFileName) {
+    const lVirtualTeamsAsAString = readFileSync(pVirtualTeamsFileName, {
+        encoding: "utf-8",
+    });
+    return parseYaml(lVirtualTeamsAsAString);
+}

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

@@ -0,0 +1,8 @@
+import { readFileSync } from "node:fs";
+import { parse as parseVirtualCodeOwners } from "./parse.js";
+export default function readVirtualCodeOwners(pVirtualCodeOwnersFileName, pTeamMap) {
+    const lVirtualCodeOwnersAsAString = readFileSync(pVirtualCodeOwnersFileName, {
+        encoding: "utf-8",
+    });
+    return parseVirtualCodeOwners(lVirtualCodeOwnersAsAString, pTeamMap);
+}

package/dist/utensils.js

@@ -0,0 +1,4 @@
+export function isEmailIshUsername(pUsername) {
+    const lEmailIshUsernameRE = /^.+@.+$/;
+    return Boolean(pUsername.match(lEmailIshUsernameRE));
+}

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = "4.1.1";
+export const VERSION = "5.1.0";

package/package.json

@@ -1,17 +1,18 @@
 {
   "name": "virtual-code-owners",
-  "version": "4.1.1",
+  "version": "5.1.0",
   "description": "Merges a VIRTUAL-CODEOWNERS.txt and a virtual-teams.yml into CODEOWNERS",
   "type": "module",
   "exports": {
     ".": [
       {
-        "import": "./dist/read-and-convert.js"
+        "import": "./dist/parse-and-generate.js",
+        "types": "./types/parse-and-generate.d.ts"
       },
-      "./dist/read-and-convert.js"
+      "./dist/parse-and-generate.js"
     ]
   },
-  "main": "dist/read-and-convert.js",
+  "main": "dist/parse-and-generate.js",
   "bin": "dist/cli.js",
   "files": [
     "dist",
@@ -53,7 +54,7 @@
   },
   "devDependencies": {
     "@types/mocha": "10.0.1",
-    "@types/node": "20.2.5",
+    "@types/node": "20.3.0",
     "c8": "7.14.0",
     "dependency-cruiser": "13.0.3",
     "husky": "8.0.3",
@@ -62,7 +63,7 @@
     "prettier": "2.8.8",
     "ts-node": "10.9.1",
     "typescript": "5.1.3",
-    "upem": "7.3.2",
+    "upem": "8.0.0",
     "watskeburt": "0.11.3"
   },
   "dependencies": {

package/dist/convert-to-codeowners.js

@@ -1,56 +0,0 @@
-import { EOL } from "node:os";
-const DEFAULT_WARNING = `#${EOL}` +
-    `# DO NOT EDIT - this file is generated and your edits will be overwritten${EOL}` +
-    `#${EOL}` +
-    `# To make changes:${EOL}` +
-    `#${EOL}` +
-    `#   - edit .github/VIRTUAL-CODEOWNERS.txt${EOL}` +
-    `#   - and/ or add team members to .github/virtual-teams.yml${EOL}` +
-    `#   - run 'npx virtual-code-owners'${EOL}` +
-    `#${EOL}${EOL}`;
-export function convert(pCodeOwnersFileAsString, pTeamMap, pGeneratedWarning = DEFAULT_WARNING) {
-    return (pGeneratedWarning +
-        pCodeOwnersFileAsString
-            .split(EOL)
-            .filter(shouldAppearInResult)
-            .map(convertLine(pTeamMap))
-            .join(EOL));
-}
-function shouldAppearInResult(pLine) {
-    return !pLine.trimStart().startsWith("#!");
-}
-function convertLine(pTeamMap) {
-    return (pUntreatedLine) => {
-        const lTrimmedLine = pUntreatedLine.trim();
-        const lSplitLine = lTrimmedLine.match(/^(?<filesPattern>[^\s]+)(?<spaces>\s+)(?<userNames>.*)$/);
-        if (lTrimmedLine.startsWith("#") || !lSplitLine?.groups) {
-            return pUntreatedLine;
-        }
-        const lUserNames = replaceTeamNames(lSplitLine.groups.userNames, pTeamMap);
-        return (lSplitLine.groups.filesPattern +
-            lSplitLine.groups.spaces +
-            uniqAndSortUserNames(lUserNames));
-    };
-}
-function replaceTeamNames(pUserNames, pTeamMap) {
-    let lReturnValue = pUserNames;
-    for (let lTeamName of Object.keys(pTeamMap)) {
-        lReturnValue = lReturnValue.replace(new RegExp(`(\\s|^)@${lTeamName}(\\s|$)`, "g"), `$1${stringifyTeamMembers(pTeamMap, lTeamName)}$2`);
-    }
-    return lReturnValue;
-}
-function stringifyTeamMembers(pTeamMap, pTeamName) {
-    return pTeamMap[pTeamName].map(userNameToCodeOwner).join(" ");
-}
-function userNameToCodeOwner(pUserName) {
-    const lEmailIshUsernameRE = /^.+@.+$/;
-    if (pUserName.match(lEmailIshUsernameRE)) {
-        return pUserName;
-    }
-    return `@${pUserName}`;
-}
-function uniqAndSortUserNames(pUserNames) {
-    return Array.from(new Set(pUserNames.split(/\s+/)))
-        .sort()
-        .join(" ");
-}

package/dist/read-and-convert.js

@@ -1,13 +0,0 @@
-import { readFileSync } from "node:fs";
-import { parse } from "yaml";
-import { convert } from "./convert-to-codeowners.js";
-export function readAndConvert(pVirtualCodeOwnersFileName, pVirtualTeamsFileName) {
-    const lVirtualCodeOwnersAsAString = readFileSync(pVirtualCodeOwnersFileName, {
-        encoding: "utf-8",
-    });
-    const lVirtualTeamsAsAString = readFileSync(pVirtualTeamsFileName, {
-        encoding: "utf-8",
-    });
-    const lTeamMap = parse(lVirtualTeamsAsAString);
-    return convert(lVirtualCodeOwnersAsAString, lTeamMap);
-}