pa11y-ci-reporter-runner 2.0.4 → 3.0.0

package/LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2022 Aaron Goldenthal
+Copyright (c) 2022 - 2023 Aaron Goldenthal
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/index.d.ts

@@ -0,0 +1,99 @@
+type RunnerStates = 'afterAll' | 'beforeAll' | 'beginUrl' | 'urlResults';
+
+export type RunnerState = {
+  state: RunnerStates;
+  url: string;
+};
+
+export type Runner = {
+  /**
+   * Get the current state (state, url).
+   *
+   * @instance
+   * @returns The current runner state.
+   * @public
+   */
+  getCurrentState(): RunnerState;
+
+  /**
+   * Get the next state (state, url).
+   *
+   * @instance
+   * @returns The next runner state.
+   * @public
+   */
+  getNextState(): RunnerState;
+
+  /**
+   * Resets the runner and reporter to the initial states.
+   *
+   * @instance
+   * @async
+   * @public
+   */
+  reset(): void;
+
+  /**
+   * Executes the entire Pa11y CI sequence, calling all reporter functions.
+   *
+   * @instance
+   * @async
+   * @public
+   */
+  runAll(): void;
+
+  /**
+   * Executes the next event in the Pa11y CI sequence, calling the
+   * appropriate reporter function.
+   *
+   * @instance
+   * @async
+   * @public
+   */
+  runNext(): void;
+
+  /**
+   * Executes the entire Pa11y CI sequence, calling all reporter functions,
+   * 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 targetState The target state to run to.
+   * @param targetUrl The target URL to run to.
+   * @async
+   * @public
+   */
+  runUntil(state: RunnerStates, url?: string): void;
+
+  /**
+   * Executes the entire Pa11y CI sequence, calling all reporter functions,
+   * 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 targetState The target state to run to.
+   * @param targetUrl The target URL to run to.
+   * @async
+   * @public
+   */
+  runUntilNext(state: RunnerStates, url?: string): void;
+};
+
+/**
+ * Factory to create a pa11y-ci reporter runner that can execute
+ * a reporter with the specified pa11y-ci JSON results file.
+ *
+ * @param   resultsFileName Pa11y CI JSON results file.
+ * @param   reporterName    Name of the reporter to execute (module or path).
+ * @param   options         The reporter options.
+ * @param   config          The Pa11y CI configuration.
+ * @returns                 A Pa11y CI reporter runner.
+ * @static
+ * @public
+ */
+export function createRunner(
+  resultsFileName: string,
+  reporterName: string,
+  options?: object,
+  config?: object
+): Runner;

package/index.js

@@ -1,4 +1,4 @@
-/* eslint-disable max-lines */
+/* eslint-disable max-lines -- over 9 lines */
 'use strict';
 
 /**
@@ -29,6 +29,8 @@ const loadPa11yciResults = (fileName) => {
     }
 
     try {
+        // Application requires user-supplied file name
+        // nosemgrep: detect-non-literal-fs-filename, eslint.detect-non-literal-fs-filename
         const results = JSON.parse(fs.readFileSync(fileName, 'utf8'));
         return formatter.convertJsonToResultsObject(results);
     } catch (error) {
@@ -111,7 +113,7 @@ const isError = (results) =>
  * @static
  * @public
  */
-// eslint-disable-next-line max-lines-per-function
+// eslint-disable-next-line max-lines-per-function -- factory function with state
 const createRunner = (
     resultsFileName,
     reporterName,
@@ -170,6 +172,8 @@ const createRunner = (
      * @private
      */
     const urlResults = async (url) => {
+        // User supplied input used to index user supplied data file
+        // nosemgrep: eslint.detect-object-injection
         const results = pa11yciResults.results[url];
         const urlConfig = pa11yciConfig.getConfigForUrl(url);
         await (isError(results)
@@ -195,10 +199,10 @@ const createRunner = (
 
     // Collection of runner actions to be passed to the state service.
     const actions = {
+        afterAll,
         beforeAll,
         beginUrl,
-        urlResults,
-        afterAll
+        urlResults
     };
 
     // URLs for the service is always the array of result URLs since they
@@ -277,7 +281,7 @@ const createRunner = (
      * Get the current state (state, url).
      *
      * @instance
-     * @returns {object} The current state.
+     * @returns {object} The current runner state.
      * @public
      */
     // eslint-disable-next-line prefer-destructuring -- required for jsdoc
@@ -287,7 +291,7 @@ const createRunner = (
      * Get the next state (state, url).
      *
      * @instance
-     * @returns {object} The next state.
+     * @returns {object} The next runner state.
      * @public
      */
     // eslint-disable-next-line prefer-destructuring -- required for jsdoc

package/lib/default-config.js

@@ -9,9 +9,9 @@
 const defaultColumnWidth = 80;
 
 const defaultConfig = {
-    wrapWidth: process.stdout.columns || defaultColumnWidth,
     concurrency: 1,
-    useIncognitoBrowserContext: true
+    useIncognitoBrowserContext: true,
+    wrapWidth: process.stdout.columns || defaultColumnWidth
 };
 
 module.exports = defaultConfig;

package/lib/formatter.js

@@ -22,17 +22,21 @@ const isError = (issues) =>
  */
 const convertJsonToResultsObject = (jsonResults) => {
     const results = {
-        total: jsonResults.total,
-        passes: jsonResults.passes,
         errors: jsonResults.errors,
-        results: {}
+        passes: jsonResults.passes,
+        results: {},
+        total: jsonResults.total
     };
 
     for (const url of Object.keys(jsonResults.results)) {
+        // User supplied input used to index user supplied data file
+        // nosemgrep: eslint.detect-object-injection
         const issues = jsonResults.results[url];
         const formattedIssues = isError(issues)
             ? [new Error(issues[0].message)]
             : issues;
+        // User supplied input used as object key
+        // nosemgrep: eslint.detect-object-injection
         results.results[url] = formattedIssues;
     }
 
@@ -51,6 +55,8 @@ const convertJsonToResultsObject = (jsonResults) => {
  * @static
  */
 const getPa11yResultsFromPa11yCiResults = (url, results) => {
+    // User supplied input used to index user supplied data file
+    // nosemgrep: eslint.detect-object-injection
     const issues = results.results[url];
     if (!issues) {
         throw new Error(`Results for url "${url} not found`);
@@ -58,8 +64,8 @@ const getPa11yResultsFromPa11yCiResults = (url, results) => {
 
     return {
         documentTitle: `Title for ${url}`,
-        pageUrl: url,
-        issues
+        issues,
+        pageUrl: url
     };
 };
 

package/lib/pa11yci-machine.js

@@ -13,17 +13,18 @@ const { createMachine, assign } = require('xstate');
  */
 const pa11yciMachine = createMachine(
     {
-        id: 'pa11yci-runner',
-        initial: 'init',
         context: {
             urlIndex: 0,
             urls: []
         },
+        id: 'pa11yci-runner',
+        initial: 'init',
         // Opting in for v4, will be default in xstate v5
         predictableActionArguments: true,
         // Opting in for v4, will be default in xstate v5
         preserveActionOrder: true,
         states: {
+            /* eslint-disable sort-keys -- order by sequence */
             init: {
                 entry: 'setInitialUrlIndex',
                 on: {
@@ -59,6 +60,7 @@ const pa11yciMachine = createMachine(
                     RESET: { target: 'init' }
                 }
             }
+            /* eslint-enable sort-keys -- order by sequence */
         }
     },
     {

package/lib/pa11yci-service.js

@@ -1,4 +1,4 @@
-/* eslint-disable max-lines */
+/* eslint-disable max-lines -- over 22 lines */
 'use strict';
 
 /**
@@ -69,7 +69,9 @@ const hasUrl = (state) =>
  */
 const getUrlForState = (machineState) =>
     hasUrl(machineState.value)
-        ? machineState.context.urls[machineState.context.urlIndex]
+        ? // User supplied input used to index user supplied data file
+          // nosemgrep: eslint.detect-object-injection
+          machineState.context.urls[machineState.context.urlIndex]
         : undefined;
 
 /**
@@ -91,21 +93,18 @@ const validateRunnerState = (state) => {
  *
  * @param   {object}       machineState The machine state to check against.
  * @param   {RunnerStates} targetState  The target runner state.
- * @param   {string}       [targetUrl]  The target URL.
+ * @param   {string}       [targetUrl]  The target URL for the state.
  * @returns {boolean}                   True if the context matches the target, otherwise false.
  * @private
  */
-const isAtTarget = (machineState, targetState, targetUrl) => {
-    return (
-        machineState.value === targetState &&
-        (!targetUrl || getUrlForState(machineState) === targetUrl)
-    );
-};
+const isAtTarget = (machineState, targetState, targetUrl) =>
+    machineState.value === targetState &&
+    (!targetUrl || getUrlForState(machineState) === targetUrl);
 
 /**
  * Gets a summary of the machine state (state, url).
  *
- * @param   {object} machineState The machine state.
+ * @param   {object} machineState The machine state object.
  * @returns {object}              The machine state summary.
  * @private
  */
@@ -123,7 +122,7 @@ const getStateSummary = (machineState) => ({
  * @static
  * @public
  */
-// eslint-disable-next-line max-lines-per-function
+// eslint-disable-next-line max-lines-per-function -- factory function with state
 const serviceFactory = (urls, actions) => {
     let pendingCommand;
 
@@ -131,7 +130,7 @@ const serviceFactory = (urls, actions) => {
     // and the next state, which is required for some control functions.
     const pa11yMachine = machine.withContext(getInitialContext(urls));
     let currentState = pa11yMachine.initialState;
-    // machine.transition is a pure function, so only retrieves the state
+    // Machine.transition is a pure function, so only retrieves the state
     let nextState = machine.transition(currentState, MachineEvents.NEXT);
 
     /**
@@ -171,6 +170,8 @@ const serviceFactory = (urls, actions) => {
             // current state (except in init, which has no action)
             currentState = machine.transition(currentState, event);
             if (currentState.value !== 'init') {
+                // Value is internal object state
+                // nosemgrep: eslint.detect-object-injection, unsafe-dynamic-method
                 await actions[currentState.value](getUrlForState(currentState));
             }
 
@@ -216,7 +217,7 @@ const serviceFactory = (urls, actions) => {
     /**
      * Gets the state for the given state type (current or next).
      *
-     * @param   {StateTypes} stateType The state type.
+     * @param   {StateTypes} stateType The runner service state type.
      * @returns {object}               The state object for teh given type.
      * @private
      */
@@ -230,7 +231,7 @@ 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 {StateTypes}   stateType   The runner service state type.
      * @param {RunnerStates} targetState The target state to run to.
      * @param {string}       [targetUrl] The target URL to run to.
      * @async
@@ -245,6 +246,8 @@ const serviceFactory = (urls, actions) => {
             !isAtTarget(getState(stateType), targetState, targetUrl) &&
             getState(stateType).value !== finalState
         ) {
+            /* eslint-disable-next-line no-await-in-loop -- required to be
+               done in sequence */
             await sendEvent(MachineEvents.NEXT);
         }
 
@@ -292,7 +295,7 @@ const serviceFactory = (urls, actions) => {
      * Get the current state (state, url).
      *
      * @instance
-     * @returns {object} The current state.
+     * @returns {object} The current runner state.
      * @public
      */
     const getCurrentState = () => getStateSummary(currentState);
@@ -301,7 +304,7 @@ const serviceFactory = (urls, actions) => {
      * Get the next state (state, url).
      *
      * @instance
-     * @returns {object} The next state.
+     * @returns {object} The next runner state.
      * @public
      */
     const getNextState = () => getStateSummary(nextState);

package/lib/reporter-builder.js

@@ -5,15 +5,19 @@ const path = require('path');
 const reporterMethods = ['beforeAll', 'begin', 'results', 'error', 'afterAll'];
 const noop = () => {};
 
+/* eslint-disable n/global-require -- load models pa11y-ci behavior for loading
+   user-provided reporters */
 const loadReporter = (reporterName) => {
     try {
-        // eslint-disable-next-line n/global-require
+        // nosemgrep: detect-non-literal-require, eslint.detect-non-literal-require
         return require(reporterName);
     } catch {
-        // eslint-disable-next-line n/global-require
+        // nosemgrep: detect-non-literal-require, eslint.detect-non-literal-require
         return require(path.resolve(process.cwd(), reporterName));
     }
 };
+/* eslint-enable n/global-require -- load models pa11y-ci behavior for loading
+   user-provided reporters */
 
 /**
  * Creates a reporter object for the specified path, following the logic
@@ -22,7 +26,7 @@ const loadReporter = (reporterName) => {
  *
  * @param   {string}    reporterName Name of the reporter to execute
  *                                   (module or path).
- * @param   {object}    options      The reporter options.
+ * @param   {object}    options      The reporter options object.
  * @param   {object}    config       The Pa11y CI configuration.
  * @returns {object}                 The reporter object.
  * @throws  {TypeError}              Throws if reporterName is not a string.
@@ -39,7 +43,11 @@ const buildReporter = (reporterName, options, config) => {
             reporter = reporter(options, config);
         }
         for (const method of reporterMethods) {
+            // Value is internal object state
+            // nosemgrep: eslint.detect-object-injection
             if (typeof reporter[method] !== 'function') {
+                // Value is internal object state
+                // nosemgrep: eslint.detect-object-injection
                 reporter[method] = noop;
             }
         }

package/lib/runner-states.js

@@ -14,10 +14,10 @@
  * @static
  */
 const RunnerStates = Object.freeze({
+    afterAll: 'afterAll',
     beforeAll: 'beforeAll',
     beginUrl: 'beginUrl',
-    urlResults: 'urlResults',
-    afterAll: 'afterAll'
+    urlResults: 'urlResults'
 });
 
 module.exports = RunnerStates;

package/package.json

@@ -1,21 +1,23 @@
 {
   "name": "pa11y-ci-reporter-runner",
-  "version": "2.0.4",
+  "version": "3.0.0",
   "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": {
+    "build-types": "tsc index.js --declaration --allowJs --emitDeclarationOnly",
     "hooks-pre-commit": "npm run lint && npm run prettier-check",
     "hooks-pre-push": "npm audit --audit-level=critical && npm test",
     "lint": "npm run lint-js && npm run lint-md",
     "lint-js": "eslint .",
-    "lint-md": "markdownlint **/*.md --ignore node_modules --ignore Archive",
+    "lint-md": "markdownlint-cli2 \"**/*.md\" \"#node_modules\" \"#Archive\"",
     "prettier-check": "prettier --check .",
     "prettier-fix": "prettier --write .",
-    "test": "jest --ci"
+    "test": "jest --ci",
+    "test-types": "tsd"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://gitlab.com/gitlab-ci-utils/pa11y-ci-reporter-runner.git"
+    "url": "https://gitlab.com/gitlab-ci-utils/pa11y-ci-reporter-runner.git"
   },
   "keywords": [
     "pa11y-ci",
@@ -27,9 +29,10 @@
   "author": "Aaron Goldenthal <npm@aarongoldenthal.com>",
   "license": "MIT",
   "engines": {
-    "node": "^14.15.0 || ^16.13.0 || >=18.0.0"
+    "node": "^16.13.0 || ^18.12.0 || >=20.0.0"
   },
   "files": [
+    "index.d.ts",
     "index.js",
     "lib/"
   ],
@@ -38,16 +41,18 @@
   },
   "homepage": "https://gitlab.com/gitlab-ci-utils/pa11y-ci-reporter-runner",
   "devDependencies": {
-    "@aarongoldenthal/eslint-config-standard": "^19.0.1",
-    "eslint": "^8.30.0",
-    "jest": "^29.3.1",
-    "jest-junit": "^15.0.0",
-    "markdownlint-cli": "^0.32.2",
+    "@aarongoldenthal/eslint-config-standard": "^22.1.0",
+    "eslint": "^8.42.0",
+    "jest": "^29.5.0",
+    "jest-junit": "^16.0.0",
+    "markdownlint-cli2": "^0.7.1",
     "pa11y-ci-reporter-cli-summary": "^2.0.2",
-    "prettier": "^2.8.1"
+    "prettier": "^2.8.8",
+    "tsd": "^0.28.1",
+    "typescript": "^5.1.3"
   },
   "dependencies": {
     "lodash": "^4.17.21",
-    "xstate": "^4.35.1"
+    "xstate": "^4.37.2"
   }
 }