state-machine-cat 10.1.2 → 10.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "state-machine-cat",
-  "version": "10.1.2",
+  "version": "10.1.5",
   "description": "write beautiful state charts",
   "main": "./dist/commonjs/index.js",
   "module": "./src/index.mjs",
@@ -38,10 +38,9 @@
     "depcruise:graph:dev": "wireit",
     "depcruise:graph:dev:flat": "wireit",
     "depcruise:view-report": "wireit",
-    "depcruise:github-actions:markdown": "wireit",
-    "depcruise:github-actions:mermaid": "wireit",
-    "depcruise:github-actions:mermaid:affected": "wireit",
-    "depcruise:github-actions:mermaid:diff": "wireit",
+    "depcruise:github-actions:markdown": "depcruise bin src test types --config config/dependency-cruiser.js --output-type markdown",
+    "depcruise:github-actions:mermaid": "depcruise bin src --include-only '^(bin|src)' --config config/dependency-cruiser.js --output-type mermaid",
+    "depcruise:github-actions:mermaid:affected": "depcruise bin src test types tools --config config/dependency-cruiser.js --output-type mermaid --reaches \"$(watskeburt $SHA -T regex)\"",
     "lint": "wireit",
     "lint:eslint": "wireit",
     "lint:prettier": "wireit",
@@ -90,11 +89,6 @@
         "policy": "wanted",
         "because": "fast-xml-parser 4 has some breaking changes we still need to grok (why? how?)"
       },
-      {
-        "package": "husky",
-        "policy": "pin",
-        "because": "(npm7 & husky don't play nice together - and it might be it's not going to be solved satisfactorily) https://github.com/typicode/husky/issues/822 "
-      },
       {
         "package": "viz.js",
         "policy": "pin",
@@ -120,7 +114,7 @@
       "packageLocks": []
     },
     "depcruise:json": {
-      "command": "dependency-cruise --progress none --output-type json --output-to node_modules/.cache/depcruise-cache.json --config config/dependency-cruiser.js src test bin",
+      "command": "dependency-cruise --progress performance-log --output-type json --output-to node_modules/.cache/depcruise-cache.json --config config/dependency-cruiser.js src test bin",
       "files": [
         "src/**/*",
         "test/**/*",
@@ -244,13 +238,13 @@
       ]
     },
     "depcruise:graph:dev": {
-      "command": "depcruise-fmt node_modules/.cache/depcruise-cache.json --output-type dot --include-only '^(bin|src|package\\.json)' --prefix vscode://file/$(pwd)/ | dot -Tsvg | depcruise-wrap-stream-in-html | browser",
+      "command": "depcruise-fmt node_modules/.cache/depcruise-cache.json --output-type dot --include-only '^(bin|src|package\\.json)' --prefix vscode://file/$(pwd)/ --highlight \"$(watskeburt develop)\"| dot -Tsvg | depcruise-wrap-stream-in-html | browser",
       "dependencies": [
         "depcruise:json"
       ]
     },
     "depcruise:graph:dev:flat": {
-      "command": "depcruise-fmt node_modules/.cache/depcruise-cache.json --output-type flat --include-only '^(bin|src|package\\.json)' --prefix vscode://file/$(pwd)/ | twopi -Tsvg | depcruise-wrap-stream-in-html | browser",
+      "command": "depcruise-fmt node_modules/.cache/depcruise-cache.json --output-type flat --include-only '^(bin|src|package\\.json)' --prefix vscode://file/$(pwd)/ --highlight \"$(watskeburt develop)\"| twopi -Tsvg | depcruise-wrap-stream-in-html | browser",
       "dependencies": [
         "depcruise:json"
       ]
@@ -261,30 +255,6 @@
         "depcruise:json"
       ]
     },
-    "depcruise:github-actions:markdown": {
-      "command": "depcruise-fmt node_modules/.cache/depcruise-cache.json --output-type markdown >> $GITHUB_STEP_SUMMARY",
-      "dependencies": [
-        "depcruise:json"
-      ]
-    },
-    "depcruise:github-actions:mermaid": {
-      "command": "echo '\n\n```mermaid' >> $GITHUB_STEP_SUMMARY && depcruise-fmt node_modules/.cache/depcruise-cache.json --include-only '^(bin|src)' --output-type mermaid >> $GITHUB_STEP_SUMMARY && echo '```\n\n' >> $GITHUB_STEP_SUMMARY",
-      "dependencies": [
-        "depcruise:json"
-      ]
-    },
-    "depcruise:github-actions:mermaid:affected": {
-      "command": "echo '\n\n```mermaid' >> $GITHUB_STEP_SUMMARY && depcruise-fmt node_modules/.cache/depcruise-cache.json --include-only --reaches '$(watskeburt $SHA -T regex)' --output-type mermaid >> $GITHUB_STEP_SUMMARY && echo '```\n\n' >> $GITHUB_STEP_SUMMARY",
-      "dependencies": [
-        "depcruise:json"
-      ]
-    },
-    "depcruise:github-actions:mermaid:diff": {
-      "command": "echo '\n\n```mermaid' >> $GITHUB_STEP_SUMMARY && depcruise-fmt node_modules/.cache/depcruise-cache.json --include-only '^(bin|src)' --highlight '$(watskeburt $SHA -T regex)' --output-type mermaid >> $GITHUB_STEP_SUMMARY && echo '```\n\n' >> $GITHUB_STEP_SUMMARY",
-      "dependencies": [
-        "depcruise:json"
-      ]
-    },
     "lint": {
       "dependencies": [
         "lint:eslint",
@@ -301,7 +271,7 @@
       ]
     },
     "lint:prettier": {
-      "command": "prettier --check \"bin/*.mjs\" \"{src,test}/**/*.{js,mjs}\" \"{config,test}/**/*.{js,json}\" \"tools/*.{js,mjs,json}\" \"types/*.ts\" \"*.{json,yml,md}\" \"docs/{smcat-online-interpreter.js,*.md}\"",
+      "command": "prettier --check \"bin/*.mjs\" \"{src,test}/**/*.{js,mjs}\" \"{config,test}/**/*.{js,json}\" \"tools/*.{js,mjs,json}\" \"{src,types}/**/*.{ts,mts}\" \"*.{json,yml,md}\" \"docs/{smcat-online-interpreter.js,*.md}\"",
       "files": [
         "bin/*.mjs",
         "{src,test}/**/*.{js,mjs}",
@@ -319,15 +289,15 @@
       ]
     },
     "lint:types:tsc": {
-      "command": "tsc --noEmit --strict --types --noUnusedLocals --noUnusedParameters --pretty types/*.d.ts",
+      "command": "tsc --noEmit --strict --types --noUnusedLocals --noUnusedParameters --pretty types/*.d.ts src/cli/*.d.mts src/cli/*.d.ts src/parse/scxml/*.d.ts",
       "files": [
         "types/*.d.ts"
       ]
     },
     "lint:types:eslint": {
-      "command": "eslint types/*.d.ts",
+      "command": "eslint types/*.d.ts src/cli/*.d.mts src/cli/*.d.ts src/parse/scxml/*.d.ts",
       "files": [
-        "types/*.d.ts",
+        "{src,types}/**/*.d.{ts,mts}",
         ".eslintrc.json"
       ]
     },
@@ -347,10 +317,10 @@
       ]
     },
     "lint:fix:prettier": {
-      "command": "prettier --loglevel warn --write \"bin/*.mjs\" \"{src,test}/**/*.{js,mjs}\" \"{config,test}/**/*.{js,json}\" \"tools/*.{js,mjs,json}\" \"types/*.ts\" \"*.{json,yml,md}\" \"docs/{smcat-online-interpreter.js,*.md}\"",
+      "command": "prettier --loglevel warn --write \"bin/*.mjs\" \"{src,test}/**/*.{js,mjs}\" \"{config,test}/**/*.{js,json}\" \"tools/*.{js,mjs,json}\" \"{src,types}/**/*.{ts,mts}\" \"*.{json,yml,md}\" \"docs/{smcat-online-interpreter.js,*.md}\"",
       "files": [
         "bin/*.mjs",
-        "{src,test}/**/*.{js,mjs}",
+        "{src,test}/**/*.{js,mjs,ts,mts}",
         "{config,test}/**/*.{js,json}",
         "tools/*.{js,mjs,json}",
         "types/*.ts",
@@ -359,9 +329,9 @@
       ]
     },
     "lint:fix:types": {
-      "command": "eslint --fix types/*.d.ts",
+      "command": "eslint --fix types/*.d.ts src/cli/*.d.mts src/cli/*.d.ts src/parse/scxml/*.d.ts",
       "files": [
-        "types/*.d.ts",
+        "{src,types}/**/*.d.{ts,mts}",
         ".eslintrc.json"
       ]
     },
@@ -372,9 +342,10 @@
       ]
     },
     "test:cover": {
-      "command": "c8 --all --check-coverage --statements 100 --branches 99.1 --functions 100 --lines 100 --exclude \"{bin/*,config/**/*,coverage/**/*,docs/**/*,public/**/*,test/**/*,tools/**/*,types/**/*,dist/commonjs/*,src/**/*{template,-parser}.{mjs,cjs,js},tmp*}\" --reporter text-summary --reporter html --reporter lcov mocha",
+      "command": "c8 --all --check-coverage --statements 100 --branches 99.1 --functions 100 --lines 100 --exclude \"{bin/*,config/**/*,coverage/**/*,docs/**/*,public/**/*,test/**/*,tools/**/*,types/**/*,dist/commonjs/*,src/**/*.d.{ts,mts},src/**/*{template,-parser}.{mjs,cjs,js},tmp*}\" --reporter text-summary --reporter html --reporter lcov --reporter json-summary mocha",
       "output": [
-        "coverage/lcov.info"
+        "coverage/lcov.info",
+        "coverage/coverage-summary.json"
       ],
       "files": [
         "{src,test}/**/*.{js,mjs,json}"
@@ -400,9 +371,9 @@
     "state-machine-cat": "bin/smcat.mjs"
   },
   "dependencies": {
-    "ajv": "8.11.0",
-    "chalk": "5.1.2",
-    "commander": "9.4.1",
+    "ajv": "8.12.0",
+    "chalk": "5.2.0",
+    "commander": "10.0.0",
     "fast-xml-parser": "3.21.1",
     "get-stream": "6.0.1",
     "handlebars": "4.7.7",
@@ -414,38 +385,38 @@
     "wrap-ansi": "8.0.1"
   },
   "devDependencies": {
-    "@typescript-eslint/eslint-plugin": "5.40.1",
-    "@typescript-eslint/parser": "5.40.1",
+    "@typescript-eslint/eslint-plugin": "5.48.2",
+    "@typescript-eslint/parser": "5.48.2",
     "c8": "7.12.0",
-    "chai": "4.3.6",
+    "chai": "4.3.7",
     "chai-as-promised": "7.1.1",
     "chai-json-schema": "1.5.1",
     "chai-xml": "0.4.0",
-    "dependency-cruiser": "11.17.0",
-    "esbuild": "0.15.12",
-    "eslint": "8.26.0",
+    "dependency-cruiser": "12.5.1",
+    "esbuild": "0.17.3",
+    "eslint": "8.32.0",
     "eslint-config-moving-meadow": "4.0.2",
-    "eslint-config-prettier": "8.5.0",
+    "eslint-config-prettier": "8.6.0",
     "eslint-plugin-budapestian": "5.0.1",
     "eslint-plugin-eslint-comments": "3.2.0",
-    "eslint-plugin-import": "2.26.0",
+    "eslint-plugin-import": "2.27.5",
     "eslint-plugin-mocha": "10.1.0",
     "eslint-plugin-node": "11.1.0",
-    "eslint-plugin-security": "1.5.0",
-    "eslint-plugin-unicorn": "44.0.2",
-    "husky": "8.0.1",
+    "eslint-plugin-security": "1.6.0",
+    "eslint-plugin-unicorn": "45.0.2",
+    "husky": "8.0.3",
     "is-pdf": "1.0.0",
     "is-png": "3.0.1",
-    "lint-staged": "13.0.3",
-    "mocha": "10.1.0",
+    "lint-staged": "13.1.0",
+    "mocha": "10.2.0",
     "npm-run-all": "4.1.5",
     "peggy": "2.0.1",
-    "prettier": "2.7.1",
-    "query-string": "7.1.1",
-    "typescript": "4.8.4",
-    "upem": "7.3.0",
-    "watskeburt": "0.8.1",
-    "wireit": "0.7.2",
+    "prettier": "2.8.3",
+    "query-string": "8.1.0",
+    "typescript": "4.9.4",
+    "upem": "7.3.1",
+    "watskeburt": "0.9.0",
+    "wireit": "0.9.3",
     "xml-name-validator": "4.0.0"
   },
   "eslintIgnore": [

package/src/cli/actions.mjs

@@ -1,3 +1,4 @@
+// @ts-check
 import getStream from "get-stream";
 import smcat from "../index-node.mjs";
 import { getOutStream, getInStream } from "./file-name-to-stream.mjs";
@@ -31,7 +32,11 @@ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 `;
 
 export default {
+  /** @type {string} */
   LICENSE,
+  /**
+   * @param {import("./cli").ICLIRenderOptions} pOptions
+   */
   transform(pOptions) {
     return getStream(getInStream(pOptions.inputFrom)).then((pInput) => {
       const lOutput = smcat.render(pInput, {
@@ -54,6 +59,10 @@ export default {
     });
   },
 
+  /**
+   * @param {any} pError
+   * @returns {string}
+   */
   formatError(pError) {
     if (Boolean(pError.location)) {
       return `\n  syntax error on line ${pError.location.start.line}, column ${pError.location.start.column}:\n  ${pError.message}\n\n`;

package/src/cli/file-name-to-stream.mjs

@@ -1,11 +1,10 @@
+// @ts-check
 /* eslint-disable security/detect-non-literal-fs-filename */
-
-import * as fs from "node:fs";
+import fs from "node:fs";
 
 /**
- *
  * @param {string} pOutputTo
- * @returns {import("node:fs").WriteStream}
+ * @returns {NodeJS.WritableStream}
  */
 export function getOutStream(pOutputTo) {
   if ("-" === pOutputTo) {
@@ -13,10 +12,10 @@ export function getOutStream(pOutputTo) {
   }
   return fs.createWriteStream(pOutputTo);
 }
+
 /**
- *
  * @param {string} pInputFrom
- * @returns {import("node:fs").ReadStream}
+ * @returns {NodeJS.ReadableStream}
  */
 export function getInStream(pInputFrom) {
   if ("-" === pInputFrom) {

package/src/cli/make-description.mjs

@@ -1,3 +1,4 @@
+// @ts-check
 // seems eslint-plugin-import and eslint-plugin-node can't handle exports
 // fields yet. No man overboard not checking against this, because dependency-cruiser
 // will also find them
@@ -7,6 +8,10 @@ import indentString from "indent-string";
 import wrapAnsi from "wrap-ansi";
 import dotToVectorNative from "../render/vector/dot-to-vector-native.mjs";
 
+/**
+ * @param {string} pString
+ * @returns {string}
+ */
 function wrapAndIndent(pString) {
   const lDogmaticMaxConsoleWidth = 78;
   const lDefaultIndent = 2;
@@ -16,6 +21,10 @@ function wrapAndIndent(pString) {
   return indentString(wrapAnsi(pString, lMaxWidth), lDefaultIndent);
 }
 
+/**
+ * @param {boolean} pDotIsAvailable
+ * @return {string}
+ */
 export default (pDotIsAvailable = dotToVectorNative.isAvailable({})) => {
   const lDescription =
     "Write beautiful state charts - https://github.com/sverweij/state-machine-cat";

package/src/cli/normalize.mjs

@@ -1,8 +1,13 @@
-/* eslint-disable security/detect-object-injection */
+// @ts-check
+/* eslint-disable security/detect-object-injection, no-inline-comments */
 import path from "node:path";
 import options from "../options.mjs";
 import { parse as parseAttributes } from "./attributes-parser.mjs";
 
+/**
+ * @typedef {{[extension: string]: string}} DictionaryType
+ */
+
 const INPUT_EXTENSIONS = {
   ".smcat": "smcat",
   ".scxml": "scxml",
@@ -10,17 +15,20 @@ const INPUT_EXTENSIONS = {
   ".json": "json",
   ".ast": "json",
 };
+
 const OUTPUT_EXTENSIONS = {
-  ".smcat": "smcat",
+  ".ast": "json",
   ".dot": "dot",
+  ".eps": "eps",
   ".json": "json",
-  ".ast": "json",
+  ".pdf": "pdf",
+  ".png": "png",
+  ".ps": "ps",
+  ".ps2": "ps2",
   ".scjson": "scjson",
   ".scxml": "scxml",
+  ".smcat": "smcat",
   ".svg": "svg",
-  ".ps": "ps",
-  ".ps2": "ps2",
-  ".eps": "eps",
 };
 
 /**
@@ -31,7 +39,7 @@ const OUTPUT_EXTENSIONS = {
  * When in doubt returns pDefault
  *
  * @param {string} pString - filename
- * @param {object} pExtensionMap - a dictionary with
+ * @param {DictionaryType} pExtensionMap - a dictionary with
  *        extension : classification pairs
  * @param {string} pDefault - the default to return when the extension
  *        does not occur in the extension map
@@ -42,15 +50,26 @@ function classifyExtension(pString, pExtensionMap, pDefault) {
   return pExtensionMap[path.extname(pString)] || pDefault;
 }
 
+/**
+ * @param {import("../..").OutputType} pOutputType
+ * @returns {import("../..").OutputType}
+ */
 function outputType2Extension(pOutputType) {
   const lExceptions = {
-    oldsvg: "svg",
-    oldps2: "ps",
     oldeps: "eps",
+    oldps: "ps",
+    oldps2: "ps",
+    oldsvg: "svg",
     ps2: "ps",
   };
   return lExceptions[pOutputType] || pOutputType;
 }
+
+/**
+ * @param {string} pInputFrom
+ * @param {import("../..").OutputType} pOutputType
+ * @returns {string}
+ */
 function deriveOutputFromInput(pInputFrom, pOutputType) {
   const lExtension = outputType2Extension(pOutputType);
 
@@ -66,46 +85,79 @@ function deriveOutputFromInput(pInputFrom, pOutputType) {
     .concat(lExtension);
 }
 
+/**
+ * @param {string|undefined} pOutputTo
+ * @param {string} pInputFrom
+ * @param {import("../..").OutputType} pOutputType
+ * @returns {string}
+ */
 function determineOutputTo(pOutputTo, pInputFrom, pOutputType) {
-  return Boolean(pOutputTo)
-    ? pOutputTo
-    : deriveOutputFromInput(pInputFrom, pOutputType);
+  return pOutputTo ? pOutputTo : deriveOutputFromInput(pInputFrom, pOutputType);
 }
 
-function determineInputType(pInputType, pInputFrom) {
+/**
+ * @param {string} pInputFrom
+ * @param {import("../..").InputType} [pInputType]
+ * @returns {import("../..").InputType}
+ */
+function determineInputType(pInputFrom, pInputType) {
   if (pInputType) {
     return pInputType;
   }
+  // @ts-expect-error we can safely cast this to InputType. classifyExtension
+  // can probably use treatment with a generic, but with jsdoc annotations
+  // if at all possible would likely be awkward.
   return classifyExtension(
     pInputFrom,
     INPUT_EXTENSIONS,
     options.getAllowedValues().inputType.default
   );
 }
-
-function determineOutputType(pOutputType, pOutputTo) {
-  if (Boolean(pOutputType)) {
+/**
+ *
+ * @param {string} [pOutputTo]
+ * @param {import("../..").OutputType} [pOutputType]
+ * @returns {import("../..").OutputType}
+ */
+function determineOutputType(pOutputTo, pOutputType) {
+  if (pOutputType) {
     return pOutputType;
   }
-  if (Boolean(pOutputTo)) {
+  if (pOutputTo) {
+    // @ts-expect-error we can safely cast this to OutputType. classifyExtension
+    // can probably use treatment with a generic, but with jsdoc annotations
+    // if at all possible would likely be awkward.
     return classifyExtension(
       pOutputTo,
       OUTPUT_EXTENSIONS,
       options.getAllowedValues().outputType.default
     );
   }
+  // @ts-expect-error cast to OutputType is safe - see above
   return options.getAllowedValues().outputType.default;
 }
-
+/**
+ *
+ * @param {import("./cli").ILooseCLIRenderOptions} pOptions
+ * @param {string} pParameter
+ * @returns string
+ */
 function determineParameter(pOptions, pParameter) {
   return Object.prototype.hasOwnProperty.call(pOptions, pParameter)
     ? pOptions[pParameter]
     : options.getAllowedValues()[pParameter].default;
 }
 
+/**
+ * @param {Partial<import("./cli").ILooseCLIRenderOptions>} pOptions
+ * @param {keyof import("./cli").ILooseCLIRenderOptions} pDotAttributes
+ * @returns {import("../..").dotAttributesType}
+ */
 function determineDotAttributes(pOptions, pDotAttributes) {
-  return Object.prototype.hasOwnProperty.call(pOptions, pDotAttributes)
-    ? parseAttributes(pOptions[pDotAttributes])
+  return Boolean(pOptions?.[pDotAttributes]) &&
+    typeof pOptions[pDotAttributes] === "string"
+    ? // @ts-expect-error parseAttributes expects a string - which we can guarantee (see above) - but tsc can't/ doesn't see it
+      parseAttributes(pOptions[pDotAttributes])
     : [];
 }
 
@@ -114,38 +166,39 @@ function determineDotAttributes(pOptions, pDotAttributes) {
  *
  * - guesses the input type when not given
  * - guesses the output type when not given
- * - gueses the filename to output to when not given
+ * - guesses the filename to output to when not given
  * - translates parserOutput to a regular output type
  *
  * @param  {string} pArgument an argument (containing the filename to parse)
- * @param  {object} pOptions a commander options object
- * @return {object} a commander options object with options 'normalized'
+ * @param  {import("./cli").ILooseCLIRenderOptions} pLooseOptions
+ * @return {import("./cli").ICLIRenderOptions}
+ *          the passed options object, but normalized
  */
-export default function normalize(pArgument = "-", pOptions = {}) {
-  const lReturnValue = { ...pOptions };
-
-  lReturnValue.inputFrom = pArgument || "-";
-  lReturnValue.inputType = determineInputType(
-    pOptions.inputType,
-    lReturnValue.inputFrom
-  );
-  lReturnValue.outputType = determineOutputType(
-    pOptions.outputType,
-    pOptions.outputTo
+export default function normalize(pArgument = "-", pLooseOptions = {}) {
+  const lNormalizedInputFrom = pArgument || "-";
+  const lNormalizedInputType = determineInputType(
+    lNormalizedInputFrom,
+    pLooseOptions.inputType
   );
-  lReturnValue.outputTo = determineOutputTo(
-    pOptions.outputTo,
-    lReturnValue.inputFrom,
-    lReturnValue.outputType
+  const lNormalizedOutputType = determineOutputType(
+    pLooseOptions.outputTo,
+    pLooseOptions.outputType
   );
-  lReturnValue.engine = determineParameter(pOptions, "engine");
-  lReturnValue.direction = determineParameter(pOptions, "direction");
-  lReturnValue.dotGraphAttrs = determineDotAttributes(
-    pOptions,
-    "dotGraphAttrs"
-  );
-  lReturnValue.dotNodeAttrs = determineDotAttributes(pOptions, "dotNodeAttrs");
-  lReturnValue.dotEdgeAttrs = determineDotAttributes(pOptions, "dotEdgeAttrs");
 
-  return lReturnValue;
+  return {
+    inputFrom: lNormalizedInputFrom,
+    inputType: lNormalizedInputType,
+    outputType: lNormalizedOutputType,
+    outputTo: determineOutputTo(
+      pLooseOptions.outputTo,
+      lNormalizedInputFrom,
+      lNormalizedOutputType
+    ),
+    engine: determineParameter(pLooseOptions, "engine"),
+    direction: determineParameter(pLooseOptions, "direction"),
+    dotGraphAttrs: determineDotAttributes(pLooseOptions, "dotGraphAttrs"),
+    dotNodeAttrs: determineDotAttributes(pLooseOptions, "dotNodeAttrs"),
+    dotEdgeAttrs: determineDotAttributes(pLooseOptions, "dotEdgeAttrs"),
+    desugar: pLooseOptions?.desugar ?? false,
+  };
 }

package/src/cli/validations.mjs

@@ -1,9 +1,14 @@
+// @ts-check
 import fs from "node:fs";
 import smcat from "../index-node.mjs";
 import { parse as parseAttributes } from "./attributes-parser.mjs";
 
 const allowedValues = smcat.getAllowedValues();
 
+/**
+ * @param {{name: string}} pValue
+ * @returns {string}
+ */
 function getName(pValue) {
   return pValue.name;
 }
@@ -13,14 +18,22 @@ const VALID_INPUT_TYPES = allowedValues.inputType.values.map(getName);
 const VALID_ENGINES = allowedValues.engine.values.map(getName);
 const VALID_DIRECTIONS = allowedValues.direction.values.map(getName);
 
+/**
+ * @param {string} pFilename
+ * @returns {boolean}
+ */
 function isStdout(pFilename) {
   return "-" === pFilename;
 }
 
+/**
+ * @param {string} pFilename
+ * @returns {boolean}
+ */
 function fileExists(pFilename) {
   try {
     if (!isStdout(pFilename)) {
-      fs.accessSync(pFilename, fs.R_OK);
+      fs.accessSync(pFilename, fs.constants.R_OK);
     }
     return true;
   } catch (pError) {
@@ -28,6 +41,15 @@ function fileExists(pFilename) {
   }
 }
 
+/**
+ * This function is shaped so it can serve as a validation function in a
+ * commander option.
+ *
+ * @param {keyof import("../../types/state-machine-cat").IRenderOptions} pOption
+ * @param {string[]} pValidValues
+ * @param {string} pError
+ * @returns {never|keyof import("../../types/state-machine-cat").IRenderOptions}
+ */
 function validOption(pOption, pValidValues, pError) {
   if (pValidValues.includes(pOption)) {
     return pOption;
@@ -78,6 +100,10 @@ export default {
     }
   },
 
+  /**
+   * @param {import("./cli").ICLIRenderOptions} pOptions
+   * @returns {never|import("./cli").ICLIRenderOptions}
+   */
   validateArguments(pOptions) {
     if (!pOptions.inputFrom) {
       throw new Error(`\n  error: Please specify an input file.\n\n`);