pa11y-ci-reporter-runner 2.0.2 → 2.0.3

package/index.js

@@ -18,9 +18,10 @@ const RunnerStates = require('./lib/runner-states');
 /**
  * Loads the Pa11y CI results from JSON file.
  *
+ * @param   {string}    fileName Pa11y CI JSON results file name.
+ * @returns {object}             Pa11y CI results.
+ * @throws  {TypeError}          Throws if fileName is not a string.
  * @private
- * @param   {string} fileName Pa11y CI JSON results file name.
- * @returns {object}          Pa11y CI results.
  */
 const loadPa11yciResults = (fileName) => {
     if (typeof fileName !== 'string') {
@@ -40,9 +41,11 @@ const loadPa11yciResults = (fileName) => {
  * or object with url and other configuration, so this return a list of just
  * the url strings.
  *
+ * @param   {object[]}  values The urls array from configuration.
+ * @returns {string[]}         Array of URL strings.
+ * @throws  {TypeError}        Throws if URLs array contains an invalid
+ *                             URL element.
  * @private
- * @param   {object[]} values The urls array from configuration.
- * @returns {string[]}        Array of URL strings.
  */
 const getUrlList = (values) => {
     const result = [];
@@ -64,9 +67,10 @@ const getUrlList = (values) => {
  * may not be in the same order). URLs in config are only checked if
  * provided. If specified and inconsistent, throws error.
  *
+ * @param  {object}    results Pa11y CI JSON results file.
+ * @param  {object}    config  Pa11y CI configuration.
+ * @throws {TypeError}         Throws if config URLs do not match results URLs.
  * @private
- * @param   {object} results Pa11y CI JSON results file.
- * @param   {object} config  Pa11y CI configuration.
  */
 const validateUrls = (results, config) => {
     // Valid if no urls specified in config
@@ -88,9 +92,9 @@ const validateUrls = (results, config) => {
 /**
  * Check if the given Pa11y results are an execution error.
  *
- * @private
  * @param   {object}  results Pa11y results for a single URL.
  * @returns {boolean}         True if the results are an execution error.
+ * @private
  */
 const isError = (results) =>
     results.length === 1 && results[0] instanceof Error;
@@ -99,13 +103,13 @@ const isError = (results) =>
  * Factory to create a pa11y-ci reporter runner that can execute
  * a reporter with the specified pa11y-ci JSON results file.
  *
- * @public
- * @static
  * @param   {string} resultsFileName Pa11y CI JSON results file.
  * @param   {string} reporterName    Name of the reporter to execute (module or path).
  * @param   {object} options         The reporter options.
  * @param   {object} config          The Pa11y CI configuration.
  * @returns {object}                 A Pa11y CI reporter runner.
+ * @static
+ * @public
  */
 // eslint-disable-next-line max-lines-per-function
 const createRunner = (
@@ -123,8 +127,8 @@ const createRunner = (
      * Create a new reporter with the given options and config
      * (encapsulated as a function for consistency).
      *
-     * @private
      * @returns {object} The reporter associated with the runner.
+     * @private
      */
     const getReporter = () =>
         reporterBuilder.buildReporter(
@@ -149,9 +153,9 @@ const createRunner = (
     /**
      * Implements the runner beginUrl event, calling reporter.begin.
      *
+     * @param {string} url The url being analyzed.
      * @async
      * @private
-     * @param {string} url The url being analyzed.
      */
     const beginUrl = async (url) => {
         await reporter.begin(url);
@@ -161,9 +165,9 @@ const createRunner = (
      * Implements the runner urlResults event, calling reporter.results or
      * reporter.error as appropriate based on the results.
      *
+     * @param {string} url The url being analyzed.
      * @async
      * @private
-     * @param {string} url The url being analyzed.
      */
     const urlResults = async (url) => {
         const results = pa11yciResults.results[url];
@@ -207,9 +211,9 @@ const createRunner = (
     /**
      * Resets the runner and reporter to the initial states.
      *
+     * @instance
      * @async
      * @public
-     * @instance
      */
     const reset = async () => {
         await service.reset();
@@ -219,9 +223,9 @@ const createRunner = (
     /**
      * Executes the entire Pa11y CI sequence, calling all reporter functions.
      *
+     * @instance
      * @async
      * @public
-     * @instance
      */
     const runAll = async () => {
         await service.runUntil(RunnerStates.afterAll);
@@ -231,9 +235,9 @@ const createRunner = (
      * Executes the next event in the Pa11y CI sequence, calling the
      * appropriate reporter function.
      *
+     * @instance
      * @async
      * @public
-     * @instance
      */
     const runNext = async () => {
         await service.runNext();
@@ -244,11 +248,11 @@ const createRunner = (
      * until the specified current state and optional URL are reached. If a URL is not
      * specified, the run completes on the first occurrence of the target state.
      *
-     * @async
-     * @public
      * @instance
      * @param {string} targetState The target state to run to.
      * @param {string} [targetUrl] The target URL to run to.
+     * @async
+     * @public
      */
     const runUntil = async (targetState, targetUrl) => {
         await service.runUntil(targetState, targetUrl);
@@ -259,11 +263,11 @@ const createRunner = (
      * until the specified next state and optional URL are reached. If a URL is not
      * specified, the run completes on the first occurrence of the target state.
      *
-     * @async
-     * @public
      * @instance
      * @param {string} targetState The target state to run to.
      * @param {string} [targetUrl] The target URL to run to.
+     * @async
+     * @public
      */
     const runUntilNext = async (targetState, targetUrl) => {
         await service.runUntilNext(targetState, targetUrl);
@@ -272,9 +276,9 @@ const createRunner = (
     /**
      * Get the current state (state, url).
      *
-     * @public
      * @instance
      * @returns {object} The current state.
+     * @public
      */
     // eslint-disable-next-line prefer-destructuring -- required for jsdoc
     const getCurrentState = service.getCurrentState;
@@ -282,9 +286,9 @@ const createRunner = (
     /**
      * Get the next state (state, url).
      *
-     * @public
      * @instance
      * @returns {object} The next state.
+     * @public
      */
     // eslint-disable-next-line prefer-destructuring -- required for jsdoc
     const getNextState = service.getNextState;

package/lib/config.js

@@ -24,9 +24,9 @@ const normalizeConfig = (config) => {
  * configuration including defaults and determining the consolidated
  * configuration for each URL.
  *
- * @static
  * @param   {object} config The Pa11y CI configuration.
  * @returns {object}        Config object.
+ * @static
  */
 const configFactory = (config) => {
     const { defaults, urls } = normalizeConfig(config);

package/lib/formatter.js

@@ -16,9 +16,9 @@ const isError = (issues) =>
  * allowing JSON result files to be used for reporter interface
  * testing. Error messages are converted to Error objects.
  *
- * @static
  * @param   {object} jsonResults Pa11y CI JSON results.
  * @returns {object}             The equivalent Pa11y CI object.
+ * @static
  */
 const convertJsonToResultsObject = (jsonResults) => {
     const results = {
@@ -44,10 +44,11 @@ const convertJsonToResultsObject = (jsonResults) => {
  * returns a Pa11y results object of the format sent to the reporter
  * results event. Throws if the url is not found in the results.
  *
- * @static
  * @param   {string} url     The URL to find results for,.
  * @param   {object} results Pa11y CI results object.
  * @returns {object}         The Pa11y results object for the URL.
+ * @throws  {Error}          Throws if results are not found for the given URL.
+ * @static
  */
 const getPa11yResultsFromPa11yCiResults = (url, results) => {
     const issues = results.results[url];

package/lib/pa11yci-service.js

@@ -15,10 +15,10 @@ const finalState = RunnerStates.afterAll;
 /**
  * Enum for machine events.
  *
- * @enum {string}
- * @private
  * @readonly
+ * @enum {string}
  * @static
+ * @private
  */
 const MachineEvents = Object.freeze({
     NEXT: 'NEXT',
@@ -28,10 +28,10 @@ const MachineEvents = Object.freeze({
 /**
  * Enum for runner service states.
  *
- * @enum {string}
- * @private
  * @readonly
+ * @enum {string}
  * @static
+ * @private
  */
 const StateTypes = Object.freeze({
     current: 'current',
@@ -41,9 +41,9 @@ const StateTypes = Object.freeze({
 /**
  * Gets the initial pa11yci-runner state machine context given an array of URLs.
  *
- * @private
  * @param   {Array}  urls Array of URLs.
  * @returns {object}      The initial state machine context.
+ * @private
  */
 const getInitialContext = (urls) => ({
     urlIndex: 0,
@@ -53,9 +53,9 @@ const getInitialContext = (urls) => ({
 /**
  * Checks the runner state to determine whether it has an associated URL.
  *
- * @private
  * @param   {string}  state The state to check.
  * @returns {boolean}       True if the state has an associated url.
+ * @private
  */
 const hasUrl = (state) =>
     state === RunnerStates.beginUrl || state === RunnerStates.urlResults;
@@ -63,9 +63,9 @@ const hasUrl = (state) =>
 /**
  * Gets the URL for the given machine state.
  *
- * @private
  * @param   {object} machineState The machine state to check against.
  * @returns {string}              The current URL for the machine state.
+ * @private
  */
 const getUrlForState = (machineState) =>
     hasUrl(machineState.value)
@@ -75,8 +75,9 @@ const getUrlForState = (machineState) =>
 /**
  * Validates that the given state is a valid RunnerStates value. Throws if not.
  *
+ * @param  {string}    state The state to validate.
+ * @throws {TypeError}       Throws if state is not a valid RunnerStates value.
  * @private
- * @param   {string} state The state to validate.
  */
 const validateRunnerState = (state) => {
     if (!Object.keys(RunnerStates).includes(state)) {
@@ -88,11 +89,11 @@ const validateRunnerState = (state) => {
  * Checks if the machine state matches the targetState and either no
  * targetUrl was specified or the context matches the targetUrl.
  *
+ * @param   {object}       machineState The machine state to check against.
+ * @param   {RunnerStates} targetState  The target runner state.
+ * @param   {string}       [targetUrl]  The target URL.
+ * @returns {boolean}                   True if the context matches the target, otherwise false.
  * @private
- * @param   {object}        machineState The machine state to check against.
- * @param   {RunnerStates}  targetState  The target runner state.
- * @param   {string}        [targetUrl]  The target URL.
- * @returns {boolean}                    True if the context matches the target, otherwise false.
  */
 const isAtTarget = (machineState, targetState, targetUrl) => {
     return (
@@ -104,9 +105,9 @@ const isAtTarget = (machineState, targetState, targetUrl) => {
 /**
  * Gets a summary of the machine state (state, url).
  *
- * @private
  * @param   {object} machineState The machine state.
  * @returns {object}              The machine state summary.
+ * @private
  */
 const getStateSummary = (machineState) => ({
     state: machineState.value,
@@ -116,11 +117,11 @@ const getStateSummary = (machineState) => ({
 /**
  * Factory function that returns a pa11yci-runner service.
  *
- * @public
- * @static
  * @param   {Array}  urls    Array of URLs.
  * @param   {object} actions Actions object with functions to execute for each event.
  * @returns {object}         A pa11yci-runner service.
+ * @static
+ * @public
  */
 // eslint-disable-next-line max-lines-per-function
 const serviceFactory = (urls, actions) => {
@@ -136,6 +137,8 @@ const serviceFactory = (urls, actions) => {
     /**
      * Validates that a command is allowed in the given state. Throws if invalid.
      *
+     * @throws {Error} Throws if a previous command is still pending.
+     * @throws {Error} Throws if the runner state is afterAll (must reset first).
      * @private
      */
     const validateCommandAllowed = () => {
@@ -155,9 +158,9 @@ const serviceFactory = (urls, actions) => {
      * Sends the specified event to the pa11yci-machine and executes
      * the applicable action for that state.
      *
+     * @param {MachineEvents} event The event name to be sent.
      * @async
      * @private
-     * @param   {MachineEvents} event The event name to be sent.
      */
     const sendEvent = async (event) => {
         try {
@@ -188,9 +191,9 @@ const serviceFactory = (urls, actions) => {
     /**
      * Resets the service to the init state.
      *
+     * @instance
      * @async
      * @public
-     * @instance
      */
     const reset = async () => {
         await sendEvent(MachineEvents.RESET);
@@ -200,9 +203,9 @@ const serviceFactory = (urls, actions) => {
      * Executes the next event in the Pa11y CI sequence, calling the
      * appropriate reporter function.
      *
+     * @instance
      * @async
      * @public
-     * @instance
      */
     const runNext = async () => {
         validateCommandAllowed();
@@ -213,9 +216,9 @@ const serviceFactory = (urls, actions) => {
     /**
      * Gets the state for the given state type (current or next).
      *
-     * @private
      * @param   {StateTypes} stateType The state type.
      * @returns {object}               The state object for teh given type.
+     * @private
      */
     const getState = (stateType) =>
         stateType === StateTypes.current ? currentState : nextState;
@@ -227,11 +230,11 @@ const serviceFactory = (urls, actions) => {
      * specified state and optional URL are reached. If a URL is not specified,
      * the run completes on the first occurrence of the target state.
      *
+     * @param {StateTypes}   stateType   The state type.
+     * @param {RunnerStates} targetState The target state to run to.
+     * @param {string}       [targetUrl] The target URL to run to.
      * @async
      * @private
-     * @param   {StateTypes}   stateType   The state type.
-     * @param   {RunnerStates} targetState The target state to run to.
-     * @param   {string}       [targetUrl] The target URL to run to.
      */
     const runUntilInternal = async (stateType, targetState, targetUrl) => {
         validateCommandAllowed();
@@ -260,11 +263,11 @@ const serviceFactory = (urls, actions) => {
      * until the specified current state and optional URL are reached. If a URL is not
      * specified, the run completes on the first occurrence of the target state.
      *
+     * @instance
+     * @param {RunnerStates} targetState The target state to run to.
+     * @param {string}       [targetUrl] The target URL to run to.
      * @async
      * @public
-     * @instance
-     * @param    {RunnerStates} targetState The target state to run to.
-     * @param    {string}       [targetUrl] The target URL to run to.
      */
     const runUntil = async (targetState, targetUrl) => {
         await runUntilInternal(StateTypes.current, targetState, targetUrl);
@@ -275,11 +278,11 @@ const serviceFactory = (urls, actions) => {
      * until the specified next state and optional URL are reached. If a URL is not
      * specified, the run completes on the first occurrence of the target state.
      *
+     * @instance
+     * @param {RunnerStates} targetState The target state to run to.
+     * @param {string}       [targetUrl] The target URL to run to.
      * @async
      * @public
-     * @instance
-     * @param    {RunnerStates} targetState The target state to run to.
-     * @param    {string}       [targetUrl] The target URL to run to.
      */
     const runUntilNext = async (targetState, targetUrl) => {
         await runUntilInternal(StateTypes.next, targetState, targetUrl);
@@ -288,18 +291,18 @@ const serviceFactory = (urls, actions) => {
     /**
      * Get the current state (state, url).
      *
-     * @public
      * @instance
-     * @returns  {object} The current state.
+     * @returns {object} The current state.
+     * @public
      */
     const getCurrentState = () => getStateSummary(currentState);
 
     /**
      * Get the next state (state, url).
      *
-     * @public
      * @instance
-     * @returns  {object} The next state.
+     * @returns {object} The next state.
+     * @public
      */
     const getNextState = () => getStateSummary(nextState);
 

package/lib/reporter-builder.js

@@ -20,11 +20,12 @@ const loadReporter = (reporterName) => {
  * used by pa11y-ci for reporter generation. Unlike pa11y-ci, ensures a
  * function exists for each reporter event to allow manual execution.
  *
- * @param   {string} reporterName    Name of the reporter to execute
+ * @param   {string}    reporterName Name of the reporter to execute
  *                                   (module or path).
- * @param   {object} options         The reporter options.
- * @param   {object} config          The Pa11y CI configuration.
+ * @param   {object}    options      The reporter options.
+ * @param   {object}    config       The Pa11y CI configuration.
  * @returns {object}                 The reporter object.
+ * @throws  {TypeError}              Throws if reporterName is not a string.
  */
 // eslint-disable-next-line sonarjs/cognitive-complexity -- allow < 10
 const buildReporter = (reporterName, options, config) => {

package/lib/runner-states.js

@@ -9,8 +9,8 @@
 /**
  * Enum for runner states.
  *
- * @enum {string}
  * @readonly
+ * @enum {string}
  * @static
  */
 const RunnerStates = Object.freeze({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pa11y-ci-reporter-runner",
-  "version": "2.0.2",
+  "version": "2.0.3",
   "description": "Pa11y CI Reporter Runner is designed to facilitate testing of Pa11y CI reporters. Given a Pa11y CI JSON results file and optional configuration it simulates the Pa11y CI calls to the reporter.",
   "main": "index.js",
   "scripts": {
@@ -38,16 +38,16 @@
   },
   "homepage": "https://gitlab.com/gitlab-ci-utils/pa11y-ci-reporter-runner",
   "devDependencies": {
-    "@aarongoldenthal/eslint-config-standard": "^16.0.1",
-    "eslint": "^8.23.0",
-    "jest": "^29.0.1",
+    "@aarongoldenthal/eslint-config-standard": "^17.0.1",
+    "eslint": "^8.27.0",
+    "jest": "^29.2.2",
     "jest-junit": "^14.0.1",
     "markdownlint-cli": "^0.32.2",
-    "pa11y-ci-reporter-cli-summary": "^2.0.1",
+    "pa11y-ci-reporter-cli-summary": "^2.0.2",
     "prettier": "^2.7.1"
   },
   "dependencies": {
     "lodash": "^4.17.21",
-    "xstate": "^4.33.5"
+    "xstate": "^4.34.0"
   }
 }