virtual-code-owners 6.0.0 → 6.1.1

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/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/main.js

@@ -25,6 +25,8 @@ 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 cli(pArguments = process.argv.slice(2), pOutStream = process.stdout, pErrorStream = process.stderr) {
     try {
@@ -72,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 },
         },
@@ -84,14 +90,18 @@ function main(pOptions, pErrorStream) {
     const lTeamMap = readTeamMap(pOptions.virtualTeams);
     const lVirtualCodeOwners = readVirtualCodeOwners(pOptions.virtualCodeOwners, lTeamMap);
     const lCodeOwnersContent = generateCodeOwners(lVirtualCodeOwners, lTeamMap);
-    writeFileSync(pOptions.codeOwners, lCodeOwnersContent, {
-        encoding: "utf-8",
-    });
-    if (pOptions.emitLabeler) {
-        const lLabelerContent = generateLabelerYml(lVirtualCodeOwners, lTeamMap);
-        writeFileSync(pOptions.labelerLocation, lLabelerContent, {
+    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 {

package/dist/read-team-map.js

@@ -8,10 +8,10 @@ export default function readTeamMap(pVirtualTeamsFileName) {
         encoding: "utf-8",
     });
     const lTeamMap = parseYaml(lVirtualTeamsAsAString);
-    validateTeamMap(lTeamMap, pVirtualTeamsFileName);
+    assertTeamMapValid(lTeamMap, pVirtualTeamsFileName);
     return lTeamMap;
 }
-function validateTeamMap(pTeamMap, pVirtualTeamsFileName) {
+function assertTeamMapValid(pTeamMap, pVirtualTeamsFileName) {
     const ajv = new Ajv({
         allErrors: true,
         verbose: true,

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

@@ -1,6 +1,6 @@
 import { readFileSync } from "node:fs";
 import { EOL } from "node:os";
-import { getAnomalies, parse as parseVirtualCodeOwners } from "./parse.js";
+import { getAnomalies, parse as parseVirtualCodeOwners, } from "./parse-virtual-code-owners.js";
 export default function readVirtualCodeOwners(pVirtualCodeOwnersFileName, pTeamMap) {
     const lVirtualCodeOwnersAsAString = readFileSync(pVirtualCodeOwnersFileName, {
         encoding: "utf-8",

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = "6.0.0";
+export const VERSION = "6.1.1";

package/dist/virtual-teams.schema.json

@@ -2,7 +2,7 @@
   "$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/4.1.0",
+  "$id": "org.js.virtual-code-owners/6.0.0",
   "type": "object",
   "additionalProperties": {
     "type": "array",

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "virtual-code-owners",
-  "version": "6.0.0",
-  "description": "Merges a VIRTUAL-CODEOWNERS.txt and a virtual-teams.yml into CODEOWNERS",
+  "version": "6.1.1",
+  "description": "Makes your CODEOWNERS file liveable again",
   "type": "module",
   "exports": {
     "parse": [
       {
-        "import": "./dist/parse.js",
-        "types": "./types/parse.d.ts"
+        "import": "./dist/parse-virtual-code-owners.js",
+        "types": "./types/parse-virtual-code-owners.d.ts"
       },
-      "./dist/parse.js"
+      "./dist/parse-virtual-code-owners.js"
     ],
     "generateCodeOwners": [
       {
@@ -30,7 +30,8 @@
   "types": "types/types.d.ts",
   "bin": "dist/cli.js",
   "files": [
-    "dist",
+    "dist/",
+    "types/",
     "package.json",
     "README.md",
     "LICENSE"
@@ -44,7 +45,7 @@
     "depcruise:graph:diff:dev": "depcruise src --prefix vscode://file/$(pwd)/ --output-type dot --reaches \"$(watskeburt $SHA -T regex)\"| dot -T svg | depcruise-wrap-stream-in-html | browser",
     "depcruise:graph:diff:mermaid": "depcruise src tools --output-type mermaid --output-to - --reaches \"$(watskeburt $SHA -T regex)\"",
     "depcruise:html": "depcruise src tools --output-type err-html --output-to dependency-violation-report.html",
-    "format": "prettier --loglevel warn --write \"**/*.{md,ts,json,yml}\"",
+    "format": "prettier --log-level warn --write \"**/*.{md,ts,json,yml}\"",
     "prepare": "husky install",
     "scm:stage": "git add .",
     "test": "NODE_OPTIONS=--no-warnings c8 mocha",
@@ -69,17 +70,17 @@
   },
   "devDependencies": {
     "@types/mocha": "10.0.1",
-    "@types/node": "20.3.1",
+    "@types/node": "20.4.1",
     "c8": "8.0.0",
-    "dependency-cruiser": "13.0.3",
+    "dependency-cruiser": "13.1.0",
     "husky": "8.0.3",
-    "lint-staged": "13.2.2",
+    "lint-staged": "13.2.3",
     "mocha": "10.2.0",
-    "prettier": "2.8.8",
+    "prettier": "3.0.0",
     "ts-node": "10.9.1",
-    "typescript": "5.1.3",
+    "typescript": "5.1.6",
     "upem": "8.0.0",
-    "watskeburt": "0.11.3"
+    "watskeburt": "0.11.6"
   },
   "dependencies": {
     "ajv": "8.12.0",

package/types/generate-codeowners.d.ts

@@ -0,0 +1,6 @@
+import type { ITeamMap, IVirtualCodeOwnersCST } from "./types.js";
+export default function generateCodeOwners(
+  pVirtualCodeOwners: IVirtualCodeOwnersCST,
+  pTeamMap: ITeamMap,
+  pGeneratedWarning?: string,
+): string;

package/types/generate-labeler-yml.d.ts

@@ -0,0 +1,6 @@
+import type { ITeamMap, IVirtualCodeOwnersCST } from "./types.js";
+export default function generateLabelerYml(
+  pCodeOwners: IVirtualCodeOwnersCST,
+  pTeamMap: ITeamMap,
+  pGeneratedWarning?: string,
+): string;

package/types/parse-virtual-code-owners.d.ts

@@ -0,0 +1,18 @@
+import type { IAnomaly, ITeamMap, IVirtualCodeOwnersCST } from "./types.js";
+/**
+ * parses (virtual) codeowners as a string into a virtual codeowners CST
+ * which can be used to do further  rocessing on (e.g. generate codeowners,
+ * validate etc.)
+ *
+ * @param pVirtualCodeOwnersAsString CODEOWNERS or VIRTUAL-CODE-OWNERS.txt file  to parse
+ * @param pTeamMap a virtual team map  ()
+ * @returns a virtual code owners CST
+ */
+export declare function parse(
+  pVirtualCodeOwnersAsString: string,
+  pTeamMap?: ITeamMap,
+): IVirtualCodeOwnersCST;
+
+export declare function getAnomalies(
+  pVirtualCodeOwners: IVirtualCodeOwnersCST,
+): IAnomaly[];

package/types/types.d.ts

@@ -0,0 +1,44 @@
+export interface ITeamMap {
+  [teamName: string]: string[];
+}
+
+export type IVirtualCodeOwnersCST = IVirtualCodeOwnerLine[];
+export type IVirtualCodeOwnerLine = IBoringCSTLine | IInterestingCSTLine;
+export interface IBoringCSTLine {
+  type: "comment" | "ignorable-comment" | "empty" | "unknown";
+  line: number;
+  raw: string;
+}
+export interface IInterestingCSTLine {
+  type: "rule";
+  line: number;
+  filesPattern: string;
+  spaces: string;
+  users: IUser[];
+  raw: string;
+}
+export type UserType =
+  | "virtual-team-name"
+  | "e-mail-address"
+  | "other-user-or-team"
+  | "invalid";
+export type IUser = {
+  type: UserType;
+  userNumberWithinLine: number;
+  bareName: string;
+  raw: string;
+};
+
+export type IAnomaly = ILineAnomaly | IUserAnomaly;
+export interface ILineAnomaly {
+  type: "invalid-line";
+  line: number;
+  raw: string;
+}
+export interface IUserAnomaly {
+  type: "invalid-user";
+  line: number;
+  userNumberWithinLine: number;
+  bareName: string;
+  raw: string;
+}