@emulsify/core 3.1.1 → 3.3.0

package/scripts/a11y.js

@@ -1,61 +1,113 @@
 #!/usr/bin/env node
 /**
- * @file a11y.js
- * Contains a script that, when executed, will execute a11y linting tools
- * against the storybook build.
+ * @fileoverview a11y.js
+ * Runs accessibility linting (pa11y/axe) against a Storybook build
+ * and reports issues.
  */
-const chalk = import("chalk").then(m => m.default);
 
 const R = require('ramda');
 const path = require('path');
 const pa11y = require('pa11y');
+
 const {
   storybookBuildDir,
   pa11y: pa11yConfig,
 } = require('../config/a11y.config.js');
-// project specific configuration.
+
+// Project-specific configuration.
 const {
   ignore,
   components,
 } = require('../../../config/emulsify-core/a11y.config.js');
 
+/** Absolute path to Storybook build directory. */
 const STORYBOOK_BUILD_DIR = path.resolve(__dirname, '../', storybookBuildDir);
+/** Absolute path to Storybook iframe file used for per-story rendering. */
 const STORYBOOK_IFRAME = path.join(STORYBOOK_BUILD_DIR, 'iframe.html');
 
+/**
+ * Map pa11y/axe severity to a label (historically a color name).
+ * Retained for backward compatibility, but not used for styling anymore.
+ * @deprecated Colors are no longer used; this function returns a label only.
+ * @param {'error'|'warning'|'notice'} severity
+ * @returns {'red'|'yellow'|'blue'|undefined}
+ */
 const severityToColor = R.cond([
   [R.equals('error'), R.always('red')],
   [R.equals('warning'), R.always('yellow')],
   [R.equals('notice'), R.always('blue')],
 ]);
 
-const issueIsValid = ({ code, runnerExtras: { description } }) =>
-  ignore.codes.includes(code) || ignore.descriptions.includes(description)
-    ? false
-    : true;
+/**
+ * @typedef {Object} Pa11yIssue
+ * @property {string} code - Rule identifier.
+ * @property {'error'|'warning'|'notice'} type - Severity level.
+ * @property {string} message - Human-readable description.
+ * @property {string} context - HTML context snippet.
+ * @property {string} selector - CSS selector for the node.
+ * @property {{ description?: string }} [runnerExtras] - Extra data from the runner.
+ */
+
+/**
+ * Determine whether an issue should be reported (not ignored).
+ * @param {Pa11yIssue} issue
+ * @returns {boolean} True if the issue is NOT ignored and should be logged.
+ */
+const issueIsValid = (issue) => {
+  const code = issue?.code;
+  const description = issue?.runnerExtras?.description;
+  const codeIgnored = Array.isArray(ignore?.codes) && ignore.codes.includes(code);
+  const descIgnored =
+    description &&
+    Array.isArray(ignore?.descriptions) &&
+    ignore.descriptions.includes(description);
+  return !(codeIgnored || descIgnored);
+};
 
+/**
+ * Log a single accessibility issue in a readable, colorless block.
+ * @param {Pa11yIssue} issue
+ * @returns {void}
+ */
 const logIssue = ({ type: severity, message, context, selector }) => {
-  console.log(`
-    severity: ${chalk[severityToColor(severity)](severity)}
-    message: ${message}
-    context: ${context}
-    selector: ${selector}
-  `);
+  const lines = [
+    '', // leading blank for readability
+    `severity: ${severity}`,
+    `message: ${message}`,
+    `context: ${context}`,
+    `selector: ${selector}`,
+    '',
+  ];
+  // eslint-disable-next-line no-console
+  console.log(lines.join('\n'));
 };
 
+/**
+ * Log a report for a single component/page and return whether it had issues.
+ * @param {{ issues: Pa11yIssue[], pageUrl: string }} report
+ * @returns {boolean} True if the component has at least one non-ignored issue.
+ */
 const logReport = ({ issues, pageUrl }) => {
-  const validIssues = issues.filter(issueIsValid);
+  const validIssues = (issues || []).filter(issueIsValid);
   const hasIssues = validIssues.length > 0;
 
   if (hasIssues) {
-    console.log(chalk.red(`Issues found in component: ${pageUrl}`));
-    validIssues.map(logIssue);
+    // eslint-disable-next-line no-console
+    console.log(`Issues found in component: ${pageUrl}`);
+    validIssues.forEach(logIssue);
   } else {
-    console.log(chalk.green(`No issues found in component: ${pageUrl}`));
+    // eslint-disable-next-line no-console
+    console.log(`No issues found in component: ${pageUrl}`);
   }
 
   return hasIssues;
 };
 
+/**
+ * Run pa11y on a single Storybook story by its ID.
+ * @param {string} name - Story ID (e.g., "components-button--primary").
+ * @returns {Promise<{ issues: Pa11yIssue[], pageUrl: string }>} Pa11y result.
+ */
 const lintComponent = async (name) =>
   pa11y(`${STORYBOOK_IFRAME}?id=${name}`, {
     includeNotices: true,
@@ -64,21 +116,29 @@ const lintComponent = async (name) =>
     ...pa11yConfig,
   });
 
+/**
+ * Lint a list of components, log reports, and exit(1) if any have issues.
+ * @param {string[]} names - List of Storybook story IDs.
+ * @returns {Promise<void>}
+ */
 const lintReportAndExit = R.pipe(
-  R.map(lintComponent),
-  (p) => Promise.all(p),
+  /** @param {string[]} list */
+  (list) => list.map(lintComponent),
+  (promises) => Promise.all(promises),
   R.andThen(
     R.pipe(
-      R.map(logReport),
+      /** @param {Array<{issues: Pa11yIssue[], pageUrl: string}>} results */
+      (results) => results.map(logReport),
       R.reject(R.equals(false)),
       R.unless(R.isEmpty, () => process.exit(1)),
     ),
   ),
 );
 
-// Only perform linting/reporting when instructed.
+// Only perform linting/reporting when instructed via "-r".
 /* istanbul ignore next */
 if (R.pathEq(['argv', 2], '-r')(process)) {
+  // eslint-disable-next-line promise/catch-or-return
   lintReportAndExit(components);
 }
 

package/scripts/a11y.test.js

@@ -31,7 +31,9 @@ describe('a11y', () => {
     global.console.log.mockClear();
     global.process.exit.mockClear();
   });
-  it('can map axe issue severity to the correct chalk color', () => {
+
+  it('maps axe issue severity to a label', () => {
+    // (Name no longer mentions "chalk")
     expect.assertions(3);
     expect(severityToColor('error')).toBe('red');
     expect(severityToColor('warning')).toBe('yellow');
@@ -56,7 +58,7 @@ describe('a11y', () => {
     expect(issueIsValid({ code: 'chicken', runnerExtras: {} })).toBe(true);
   });
 
-  it('can use an axe issue to generate a single log message about the issue', () => {
+  it('logs a single issue without color codes', () => {
     expect.assertions(1);
     logIssue({
       type: 'error',
@@ -65,16 +67,16 @@ describe('a11y', () => {
       selector: 'kfc > popeyes > .chicken',
     });
     expect(global.console.log.mock.calls[0][0]).toMatchInlineSnapshot(`
-      "
-          severity: error
-          message: this chicken is not fried enough.
-          context: https://example.com
-          selector: kfc > popeyes > .chicken
-        "
-    `);
+"
+severity: error
+message: this chicken is not fried enough.
+context: https://example.com
+selector: kfc > popeyes > .chicken
+"
+`);
   });
 
-  it('can log a whole axe report', () => {
+  it('logs a whole report without color codes', () => {
     const report = {
       issues: [
         {
@@ -96,45 +98,56 @@ describe('a11y', () => {
     };
     expect(logReport(report)).toBe(true);
     expect(global.console.log.mock.calls).toMatchInlineSnapshot(`
-      Array [
-        Array [
-          "Issues found in component: https://example/component.html",
-        ],
-        Array [
-          "
-          severity: error
-          message: this pizza is too soggy
-          context: https://example.com
-          selector: pizza > .hut
-        ",
-        ],
-        Array [
-          "
-          severity: error
-          message: this pasta is undercooked
-          context: https://example.com
-          selector: olive > .garden
-        ",
-        ],
-      ]
-    `);
+Array [
+  Array [
+    "Issues found in component: https://example/component.html",
+  ],
+  Array [
+    "
+severity: error
+message: this pizza is too soggy
+context: https://example.com
+selector: pizza > .hut
+",
+  ],
+  Array [
+    "
+severity: error
+message: this pasta is undercooked
+context: https://example.com
+selector: olive > .garden
+",
+  ],
+]
+`);
   });
 
-  it('logs about a component having no issue if a report comes back empty', () => {
+  it('logs that a component has no issues when a report is empty', () => {
     expect(logReport({ issues: [], pageUrl: 'papa-johns' })).toBe(false);
     expect(global.console.log.mock.calls[0][0]).toMatchInlineSnapshot(
-      `"No issues found in component: papa-johns"`,
+      `"No issues found in component: papa-johns"`,
     );
   });
 
-  it('can call pa11y with the full path to a component', async () => {
-    expect.assertions(2);
+  it('calls pa11y with the full path to a component', async () => {
+    expect.assertions(3);
     await expect(lintComponent('chicken-strips')).resolves.toBe(
       'very official report',
     );
-    expect(pa11y).toHaveBeenCalledWith(
+
+    // First arg: URL
+    expect(pa11y.mock.calls[0][0]).toBe(
       `${STORYBOOK_IFRAME}?id=chicken-strips`,
-      pa11yConfig,
+    );
+
+    // Second arg: options merged with defaults in a11y.js
+    expect(pa11y.mock.calls[0][1]).toEqual(
+      expect.objectContaining({
+        includeNotices: true,
+        includeWarnings: true,
+        runners: ['axe'],
+        ...pa11yConfig,
+      }),
     );
   });