virtual-code-owners 5.1.0 → 6.1.0

package/README.md

@@ -71,7 +71,7 @@ This is where `virtual-code-owners` comes in.
 
 ### 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) file.
+`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) file.
 The only difference between VIRTUAL-CODEOWNERS.txt and a CODEOWNERS file is that
 the _teams_ the former uses might not exist yet, except in a `virtual-teams.yml`.
 This enables you to write a _much_ easier to maintain list of code owners.
@@ -189,10 +189,10 @@ file that will check that for you.
 - ~~Currently only works for _user names_ to identify team members - not for e-mail
   addresses.~~
   Works with both user names and e-mail addresses
-- _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 be cryptic.
+- Although _virtual-code-owners_ performs basic validations on the CODEOWNER
+  format and tries to emit clear and actionable error messages about them, it
+  might not catch all of them - e.g. it doesn't check if the users in
+  virtual-teams.yml actually exist.
 
 ### Why the `.txt` extension?
 
@@ -236,3 +236,13 @@ npx virtual-code-owners --emitLabeler
 
 If you have an alternate file location for the `labeler.yml` you can specify that
 with virtual-code-owner's `--labelerLocation` parameter.
+
+### Can I just run virtual-code-owners to validate VIRTUAL-CODEOWNERS.txt & virtual-teams.yml?
+
+So _without_ generating any output?
+
+Yes. Use the `--dryRun` command line option:
+
+```
+npx virtual-code-owners --dryRun
+```

package/dist/cli.js

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
-import { main } from "./main.js";
-main();
+import { cli } from "./main.js";
+cli();

package/dist/generate-codeowners.js

@@ -20,7 +20,7 @@ export default function generateCodeOwners(pVirtualCodeOwners, pTeamMap, pGenera
 function generateLine(pCSTLine, pTeamMap) {
     if (pCSTLine.type === "rule") {
         const lUserNames = uniq(pCSTLine.users.flatMap((pUser) => expandTeamToUserNames(pUser, pTeamMap)))
-            .sort()
+            .sort(compareUserNames)
             .join(" ");
         return pCSTLine.filesPattern + pCSTLine.spaces + lUserNames;
     }
@@ -41,6 +41,9 @@ function userNameToCodeOwner(pUserName) {
     }
     return `@${pUserName}`;
 }
+function compareUserNames(pLeftName, pRightName) {
+    return pLeftName.toLowerCase() > pRightName.toLowerCase() ? 1 : -1;
+}
 function uniq(pUserNames) {
     return Array.from(new Set(pUserNames));
 }

package/dist/generate-labeler-yml.js

@@ -35,7 +35,7 @@ function transformForYamlAndMinimatch(pOriginalString) {
         lReturnValue = "**";
     }
     if (lReturnValue.startsWith("*")) {
-        lReturnValue = `'${lReturnValue}'`;
+        lReturnValue = `"${lReturnValue}"`;
     }
     if (pOriginalString.endsWith("/")) {
         lReturnValue = `${lReturnValue}**`;

package/dist/main.js

@@ -6,7 +6,6 @@ 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
@@ -26,8 +25,10 @@ Options:
                                        (default: false)
   --labelerLocation [file-name]        The location of the labeler.yml file
                                        (default: ".github/labeler.yml")
+  --dryRun                             Just validate inputs, don't generate
+                                       outputs (default: false)
   -h, --help                           display help for command`;
-export function main(pArguments = process.argv.slice(2), pOutStream = process.stdout, pErrorStream = process.stderr) {
+export function cli(pArguments = process.argv.slice(2), pOutStream = process.stdout, pErrorStream = process.stderr) {
     try {
         const lOptions = getOptions(pArguments);
         if (lOptions.help) {
@@ -38,45 +39,13 @@ export function main(pArguments = process.argv.slice(2), pOutStream = process.st
             pOutStream.write(`${VERSION}${EOL}`);
             return;
         }
-        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",
-        });
-        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}`);
-        }
+        main(lOptions, pErrorStream);
     }
     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,
@@ -105,6 +74,10 @@ function getOptions(pArguments) {
                 type: "string",
                 default: ".github/labeler.yml",
             },
+            dryRun: {
+                type: "boolean",
+                default: false,
+            },
             help: { type: "boolean", short: "h", default: false },
             version: { type: "boolean", short: "V", default: false },
         },
@@ -113,3 +86,25 @@ function getOptions(pArguments) {
         tokens: false,
     }).values;
 }
+function main(pOptions, pErrorStream) {
+    const lTeamMap = readTeamMap(pOptions.virtualTeams);
+    const lVirtualCodeOwners = readVirtualCodeOwners(pOptions.virtualCodeOwners, lTeamMap);
+    const lCodeOwnersContent = generateCodeOwners(lVirtualCodeOwners, lTeamMap);
+    if (!pOptions.dryRun) {
+        writeFileSync(pOptions.codeOwners, lCodeOwnersContent, {
+            encoding: "utf-8",
+        });
+    }
+    if (pOptions.emitLabeler) {
+        const lLabelerContent = generateLabelerYml(lVirtualCodeOwners, lTeamMap);
+        if (!pOptions.dryRun) {
+            writeFileSync(pOptions.labelerLocation, lLabelerContent, {
+                encoding: "utf-8",
+            });
+        }
+        pErrorStream.write(`${EOL}Wrote '${pOptions.codeOwners}' AND '${pOptions.labelerLocation}'${EOL}${EOL}`);
+    }
+    else {
+        pErrorStream.write(`${EOL}Wrote '${pOptions.codeOwners}'${EOL}${EOL}`);
+    }
+}

package/dist/read-team-map.js

@@ -1,8 +1,30 @@
+import Ajv from "ajv";
 import { readFileSync } from "node:fs";
+import { EOL } from "node:os";
 import { parse as parseYaml } from "yaml";
+const TEAM_MAP_SCHEMA = JSON.parse(readFileSync(new URL("./virtual-teams.schema.json", import.meta.url), "utf-8"));
 export default function readTeamMap(pVirtualTeamsFileName) {
     const lVirtualTeamsAsAString = readFileSync(pVirtualTeamsFileName, {
         encoding: "utf-8",
     });
-    return parseYaml(lVirtualTeamsAsAString);
+    const lTeamMap = parseYaml(lVirtualTeamsAsAString);
+    validateTeamMap(lTeamMap, pVirtualTeamsFileName);
+    return lTeamMap;
+}
+function validateTeamMap(pTeamMap, pVirtualTeamsFileName) {
+    const ajv = new Ajv({
+        allErrors: true,
+        verbose: true,
+    });
+    if (!ajv.validate(TEAM_MAP_SCHEMA, pTeamMap)) {
+        throw new Error(`This is not a valid virtual-teams.yml:${EOL}${formatAjvErrors(ajv.errors, pVirtualTeamsFileName)}.\n`);
+    }
+}
+function formatAjvErrors(pAjvErrors, pVirtualTeamsFileName) {
+    return pAjvErrors
+        .map((pAjvError) => formatAjvError(pAjvError, pVirtualTeamsFileName))
+        .join(EOL);
+}
+function formatAjvError(pAjvError, pVirtualTeamsFileName) {
+    return `${pVirtualTeamsFileName}: ${pAjvError.instancePath} - ${JSON.stringify(pAjvError.data)} ${pAjvError.message}`;
 }

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

@@ -1,8 +1,27 @@
 import { readFileSync } from "node:fs";
-import { parse as parseVirtualCodeOwners } from "./parse.js";
+import { EOL } from "node:os";
+import { getAnomalies, parse as parseVirtualCodeOwners, } from "./parse-virtual-code-owners.js";
 export default function readVirtualCodeOwners(pVirtualCodeOwnersFileName, pTeamMap) {
     const lVirtualCodeOwnersAsAString = readFileSync(pVirtualCodeOwnersFileName, {
         encoding: "utf-8",
     });
-    return parseVirtualCodeOwners(lVirtualCodeOwnersAsAString, pTeamMap);
+    const lVirtualCodeOwners = parseVirtualCodeOwners(lVirtualCodeOwnersAsAString, pTeamMap);
+    const lAnomalies = getAnomalies(lVirtualCodeOwners);
+    if (lAnomalies.length > 0) {
+        throw new Error(`This is not a valid virtual code-owners file:${EOL}${reportAnomalies(pVirtualCodeOwnersFileName, lAnomalies)}`);
+    }
+    return lVirtualCodeOwners;
+}
+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);
 }

package/dist/version.js

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

package/dist/virtual-teams.schema.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "virtual teams schema for virtual-code-owners",
+  "description": "a list of teams and their team members",
+  "$id": "org.js.virtual-code-owners/6.0.0",
+  "type": "object",
+  "additionalProperties": {
+    "type": "array",
+    "items": {
+      "type": "string",
+      "description": "Username or e-mail address of a team member. (Don't prefix usernames with '@')",
+      "pattern": "^[^@][^\\s]+$"
+    }
+  }
+}

package/package.json

@@ -1,18 +1,33 @@
 {
   "name": "virtual-code-owners",
-  "version": "5.1.0",
-  "description": "Merges a VIRTUAL-CODEOWNERS.txt and a virtual-teams.yml into CODEOWNERS",
+  "version": "6.1.0",
+  "description": "Makes your CODEOWNERS file liveable again",
   "type": "module",
   "exports": {
-    ".": [
+    "parse": [
       {
-        "import": "./dist/parse-and-generate.js",
-        "types": "./types/parse-and-generate.d.ts"
+        "import": "./dist/parse-virtual-code-owners.js",
+        "types": "./types/parse-virtual-code-owners.d.ts"
       },
-      "./dist/parse-and-generate.js"
+      "./dist/parse-virtual-code-owners.js"
+    ],
+    "generateCodeOwners": [
+      {
+        "import": "./dist/generate-codeowners.js",
+        "types": "./types/generate-codeowners.d.ts"
+      },
+      "./dist/generate-codeowners.js"
+    ],
+    "generateLabelerYml": [
+      {
+        "import": "./dist/generate-labeler-yml.js",
+        "types": "./types/generate-labeler-yml.d.ts"
+      },
+      "./dist/generate-labeler-yml.js"
     ]
   },
-  "main": "dist/parse-and-generate.js",
+  "main": "dist/main.js",
+  "types": "types/types.d.ts",
   "bin": "dist/cli.js",
   "files": [
     "dist",
@@ -21,7 +36,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "rm -rf dist && node --no-warnings --loader ts-node/esm tools/get-version.ts > src/version.ts && tsc",
+    "build": "rm -rf dist && node --no-warnings --loader ts-node/esm tools/get-version.ts > src/version.ts && tsc && cp -f src/*.json dist/.",
     "check": "npm run format && npm run build && npm run depcruise -- --no-progress && npm test",
     "depcruise": "depcruise src tools",
     "depcruise:graph": "depcruise src --include-only '^(src)' --output-type dot | dot -T svg | depcruise-wrap-stream-in-html > dependency-graph.html",
@@ -54,8 +69,8 @@
   },
   "devDependencies": {
     "@types/mocha": "10.0.1",
-    "@types/node": "20.3.0",
-    "c8": "7.14.0",
+    "@types/node": "20.3.1",
+    "c8": "8.0.0",
     "dependency-cruiser": "13.0.3",
     "husky": "8.0.3",
     "lint-staged": "13.2.2",
@@ -67,6 +82,7 @@
     "watskeburt": "0.11.3"
   },
   "dependencies": {
+    "ajv": "8.12.0",
     "yaml": "2.3.1"
   },
   "engines": {