@emulsify/core 3.2.0 → 3.3.1

package/config/webpack/webpack.common.js

@@ -1,26 +1,99 @@
 /**
- * @fileoverview Webpack configuration entry file.
- * This file generates Webpack entries for JS, SCSS, and SVG assets.
+ * @fileoverview Build Webpack entries and export the configuration.
+ * - Discovers JS/SCSS assets (base + component) via glob patterns
+ * - Shapes output paths based on platform and SDC (singleDirectoryComponents)
+ * - Wires up loaders, plugins, and optimizations
  */
 
-import { resolve, dirname } from 'path';
+import { posix as path } from 'node:path';
 import { sync as globSync } from 'glob';
 import fs from 'fs-extra';
+
 import loaders from './loaders.js';
 import plugins from './plugins.js';
 import resolves from './resolves.js';
 import optimizers from './optimizers.js';
 import emulsifyConfig from '../../../../../project.emulsify.json' with { type: 'json' };
 
-// Create __filename from import.meta.url without fileURLToPath
+/**
+ * Resolve the directory of this file (without fileURLToPath).
+ * @type {string}
+ */
 let _filename = decodeURIComponent(new URL(import.meta.url).pathname);
-
-// On Windows, remove the leading slash (e.g. "/C:/path" -> "C:/path")
 if (process.platform === 'win32' && _filename.startsWith('/')) {
   _filename = _filename.slice(1);
 }
+const _dirname = path.dirname(_filename);
+
+/** @type {string} Absolute project root (five levels up from this file). */
+const projectDir = path.resolve(_dirname, '../../../../..');
+
+/** @type {boolean} True when a "src/" directory exists (WP layout). */
+const hasSrc = fs.pathExistsSync(path.resolve(projectDir, 'src'));
+
+/** @type {string} The canonical source directory ("src" if present, else "components"). */
+const srcDir = hasSrc
+  ? path.resolve(projectDir, 'src')
+  : path.resolve(projectDir, 'components');
+
+/** @type {boolean} True when platform is Drupal (affects component output root). */
+const isDrupal = emulsifyConfig?.project?.platform === 'drupal';
+
+/** @type {boolean} Respect SDC (single-directory-components) layout if explicitly true. */
+const SDC = Boolean(emulsifyConfig?.project?.singleDirectoryComponents);
+
+/** @type {string} Output base for "global" assets. */
+const globalOutBase = hasSrc ? 'dist/global' : 'dist';
+
+/**
+ * Create a path under the component output root.
+ * - In Drupal + src layout, components resolve to "components/…"
+ * - Otherwise, they resolve to "dist/components/…"
+ * @param {string} subpath - Component-local subpath (no extension).
+ * @returns {string} Component output path segment.
+ */
+const componentOutPath = (subpath) =>
+  (isDrupal && hasSrc ? 'components' : 'dist/components') + '/' + subpath;
+
+/**
+ * Join segments with POSIX semantics (forward slashes), trimming empties.
+ * @param {...string} segs - Path segments.
+ * @returns {string} POSIX-joined path.
+ */
+const pj = (...segs) => path.join(...segs.filter(Boolean));
 
-const _dirname = dirname(_filename);
+/**
+ * Compute the “dist subpath” for a non-component asset.
+ * Inserts a type folder ("js" or "css") when SDC = false.
+ * Drops the original file extension.
+ * @param {string} absFile - Absolute file path.
+ * @param {'js'|'css'} type - Asset type.
+ * @returns {string} Subpath under the global output base (no extension).
+ */
+const distSubpathForBase = (absFile, type) => {
+  const rel = path.relative(srcDir, absFile);
+  const dir = path.dirname(rel);
+  const name = path.basename(rel, '.' + type);
+  return SDC ? pj(dir, name) : pj(dir, type, name);
+};
+
+/**
+ * Compute the “dist subpath” for a component asset located under "…/components".
+ * Inserts a type folder ("js" or "css") when SDC = false.
+ * Drops the original file extension.
+ * @param {string} absFile - Absolute file path.
+ * @param {'js'|'scss'} type - Source type (scss maps to 'css').
+ * @returns {string} Component-local subpath (no extension).
+ */
+const distSubpathForComponent = (absFile, type) => {
+  const relFromComponents = path.relative(pj(srcDir, 'components'), absFile);
+  const dir = path.dirname(relFromComponents);
+  const isStyle = type === 'scss';
+  const outTypeDir = isStyle ? 'css' : 'js';
+  const ext = isStyle ? '.scss' : '.js';
+  const name = path.basename(relFromComponents, ext);
+  return SDC ? pj(dir, name) : pj(dir, outTypeDir, name);
+};
 
 /**
  * Sanitize a file path by removing unwanted characters.
@@ -30,170 +103,134 @@ const _dirname = dirname(_filename);
  */
 const sanitizePath = (inputPath) => inputPath.replace(/[^a-zA-Z0-9/_-]/g, '');
 
-// Get directories for file contexts.
-const projectDir = resolve(_dirname, '../../../../..');
+/**
+ * Reject keys that could touch object internals even after sanitization.
+ * @param {string} k
+ * @returns {boolean}
+ */
+const isDangerousKey = (k) =>
+  k.includes('__proto__') || k.includes('prototype') || k === 'constructor';
+
+/**
+ * Add a file under an entry key; if the key exists, merge to an array.
+ * Keeps JS before SCSS for deterministic order.
+ *
+ * @param {Map<string, string | string[]>} map
+ * @param {string} key
+ * @param {string} file
+ * @returns {void}
+ */
+const addEntry = (map, key, file) => {
+  const safeKey = sanitizePath(String(key));
+  if (!safeKey || isDangerousKey(safeKey)) return;
 
-const srcPath = resolve(projectDir, 'src');
-const isSrcExists = fs.pathExistsSync(srcPath);
-const srcDir = isSrcExists ? srcPath : resolve(projectDir, 'components');
-const isDrupal = emulsifyConfig.project.platform === 'drupal';
+  const current = map.get(safeKey);
 
-// Glob pattern for SCSS files that ignore file names prefixed with underscore.
-const BaseScssPattern = fs.pathExistsSync(resolve(projectDir, 'src'))
-  ? resolve(srcDir, '!(components|util)/**/!(_*|cl-*|sb-*).scss')
-  : '';
-const ComponentScssPattern = fs.pathExistsSync(resolve(projectDir, 'src'))
-  ? resolve(srcDir, 'components/**/!(_*|cl-*|sb-*).scss')
-  : resolve(srcDir, '**/!(_*|cl-*|sb-*).scss');
-const ComponentLibraryScssPattern = resolve(srcDir, '**/*{cl-*,sb-*}.scss');
-
-// Glob pattern for JS files.
-const BaseJsPattern = fs.pathExistsSync(resolve(projectDir, 'src'))
-  ? resolve(
-      srcDir,
-      '!(components|util)/**/!(*.stories|*.component|*.min|*.test).js',
-    )
-  : '';
-const ComponentJsPattern = fs.pathExistsSync(resolve(projectDir, 'src'))
-  ? resolve(srcDir, 'components/**/!(*.stories|*.component|*.min|*.test).js')
-  : resolve(srcDir, '**/!(*.stories|*.component|*.min|*.test).js');
+  if (!current) {
+    map.set(safeKey, file);
+    return;
+  }
 
-// Glob pattern for SVG sprite config.
-const spritePattern = resolve(projectDir, 'assets/icons/**/*.svg');
+  const arr = Array.isArray(current) ? current : [current];
+  if (!arr.includes(file)) arr.push(file);
+
+  // Optional: ensure JS comes before SCSS
+  arr.sort((a, b) => {
+    const ax = a.endsWith('.js') ? 0 : 1;
+    const bx = b.endsWith('.js') ? 0 : 1;
+    return ax - bx || a.localeCompare(b);
+  });
+
+  map.set(safeKey, arr);
+};
 
 /**
- * Replace the last occurrence of a slash in a string with a replacement.
- *
- * @param {string} str - The original string.
- * @param {string} replacement - The string to replace the last slash with.
- * @returns {string} The modified string.
+ * Safe glob wrapper: returns [] if the pattern is falsy.
+ * @param {string} pattern - Glob pattern.
+ * @returns {string[]} Matching file paths.
  */
-function replaceLastSlash(str, replacement) {
-  const lastSlashIndex = str.lastIndexOf('/');
-  if (lastSlashIndex === -1) {
-    return str;
-  }
-  return (
-    str.slice(0, lastSlashIndex) + replacement + str.slice(lastSlashIndex + 1)
-  );
-}
+const glob = (pattern) => (pattern ? globSync(pattern) : []);
+
+/* -------------------------------------------------------------------------- */
+/*                                   GLOBS                                    */
+/* -------------------------------------------------------------------------- */
+
+const BaseScssPattern = hasSrc
+  ? pj(srcDir, '!(components|util)/**/!(_*|cl-*|sb-*).scss')
+  : '';
+
+const ComponentScssPattern = hasSrc
+  ? pj(srcDir, 'components/**/!(_*|cl-*|sb-*).scss')
+  : pj(srcDir, '**/!(_*|cl-*|sb-*).scss');
+
+const ComponentLibraryScssPattern = pj(srcDir, '**/*{cl-*,sb-*}.scss');
+
+const BaseJsPattern = hasSrc
+  ? pj(srcDir, '!(components|util)/**/!(*.stories|*.component|*.min|*.test).js')
+  : '';
+
+const ComponentJsPattern = hasSrc
+  ? pj(srcDir, 'components/**/!(*.stories|*.component|*.min|*.test).js')
+  : pj(srcDir, '**/!(*.stories|*.component|*.min|*.test).js');
+
+/* -------------------------------------------------------------------------- */
+/*                                 ENTRY BUILD                                */
+/* -------------------------------------------------------------------------- */
 
 /**
- * Generate Webpack entries for JS, SCSS, and SVG files.
- *
- * @param {string} BaseJsMatcher - Glob pattern for base JS files.
- * @param {string} jsMatcher - Glob pattern for component JS files.
- * @param {string} BaseScssMatcher - Glob pattern for base SCSS files.
- * @param {string} ComponentScssMatcher - Glob pattern for component SCSS files.
- * @param {string} ComponentLibraryScssMatcher - Glob pattern for component library SCSS files.
- * @param {string} spriteMatcher - Glob pattern for SVG sprite configuration.
- * @returns {Object} An object containing the Webpack entries.
+ * Build the complete Webpack entries map.
+ * @returns {Record<string,string>} Webpack entries.
  */
-function getEntries(
-  BaseJsMatcher,
-  jsMatcher,
-  BaseScssMatcher,
-  ComponentScssMatcher,
-  ComponentLibraryScssMatcher,
-  spriteMatcher,
-) {
-  const entries = {};
-
-  /**
-   * Add an entry to the entries object after sanitizing the key.
-   *
-   * @param {string} key - The key for the entry.
-   * @param {string} file - The file path to associate with the entry.
-   */
-  const addEntry = (key, file) => {
-    const sanitizedKey = sanitizePath(key);
-    if (
-      sanitizedKey &&
-      !Object.prototype.hasOwnProperty.call(entries, sanitizedKey)
-    ) {
-      // eslint-disable-next-line security/detect-object-injection
-      entries[sanitizedKey] = file;
-    }
-  };
-
-  // Non-component or global JS entries.
-  globSync(BaseJsMatcher).forEach((file) => {
-    const filePath = file.split(`${srcDir}/`)[1];
-    const pathParts = filePath.split('/');
-    const filePathDist = `${pathParts.slice(0, -1).join('/')}/js/${pathParts
-      .at(-1)
-      .replace('.js', '')}`;
-    const newFilePath = fs.pathExistsSync(resolve(projectDir, 'src'))
-      ? `dist/global/${filePathDist}`
-      : `dist/js/${filePathDist}`;
-    addEntry(newFilePath, file);
-  });
+const buildEntries = () => {
+  /** @type {Map<string, string | string[]>} */
+  const entries = new Map();
 
-  // Component JS entries.
-  globSync(jsMatcher).forEach((file) => {
-    if (!file.includes('dist/')) {
-      const filePath = file.split(`${srcDir}/components/`)[1];
-      const filePathDistRaw = replaceLastSlash(filePath, '/js/');
-      const filePathDist = filePathDistRaw.replace(/\.js$/, '');
-      const prefix = isDrupal && isSrcExists ? 'components' : 'dist/components';
-      const newFilePath = `${prefix}/${filePathDist}`;
-      addEntry(newFilePath, file);
-    }
-  });
+  /* ----------------------------- Base / Global JS ----------------------------- */
+  for (const file of glob(BaseJsPattern)) {
+    const sub = distSubpathForBase(file, 'js');
+    // If no "src/", legacy layout puts global JS directly under "dist/js".
+    const outRoot = hasSrc ? pj(globalOutBase) : pj('dist', 'js');
+    addEntry(entries, pj(outRoot, sub), file);
+  }
 
-  // Non-component or global SCSS entries.
-  globSync(BaseScssMatcher).forEach((file) => {
-    const filePath = file.split(`${srcDir}/`)[1];
-    const pathParts = filePath.split('/');
-    const filePathDist = `${pathParts.slice(0, -1).join('/')}/css/${pathParts
-      .at(-1)
-      .replace('.scss', '')}`;
-    const newFilePath = fs.pathExistsSync(resolve(projectDir, 'src'))
-      ? `dist/global/${filePathDist}`
-      : `dist/css/${filePathDist}`;
-    addEntry(newFilePath, file);
-  });
+  /* --------------------------- Component JS (no dist) -------------------------- */
+  for (const file of glob(ComponentJsPattern)) {
+    if (file.includes('/dist/')) continue; // guard against accidental recursion
+    const sub = distSubpathForComponent(file, 'js');
+    addEntry(entries, componentOutPath(sub), file);
+  }
 
-  // Component SCSS entries.
-  globSync(ComponentScssMatcher).forEach((file) => {
-    const filePath = file.split(`${srcDir}/components/`)[1];
-    const filePathDistRaw = replaceLastSlash(filePath, '/css/');
-    const filePathDist = filePathDistRaw.replace(/\.scss$/, '');
-    const prefix = isDrupal && isSrcExists ? 'components' : 'dist/components';
-    const newFilePath = `${prefix}/${filePathDist}`;
-    addEntry(newFilePath, file);
-  });
+  /* ------------------------------ Base / Global CSS --------------------------- */
+  for (const file of glob(BaseScssPattern)) {
+    const sub = distSubpathForBase(file, 'css');
+    // If no "src/", legacy layout puts global CSS directly under "dist/css".
+    const outRoot = hasSrc ? pj(globalOutBase) : pj('dist', 'css');
+    addEntry(entries, pj(outRoot, sub), file);
+  }
 
-  // Component Library SCSS entries.
-  globSync(ComponentLibraryScssMatcher).forEach((file) => {
-    const filePath = file.split(`${srcDir}/`)[1];
-    const newFilePath = `dist/storybook/${filePath.replace('.scss', '')}`;
-    addEntry(newFilePath, file);
-  });
+  /* ---------------------------- Component CSS (SCSS) --------------------------- */
+  for (const file of glob(ComponentScssPattern)) {
+    const sub = distSubpathForComponent(file, 'scss'); // maps to css
+    addEntry(entries, componentOutPath(sub), file);
+  }
 
-  // SVG sprite config entries.
-  globSync(spriteMatcher).forEach((file) => {
-    const filePath = file.split('/assets/')[1];
-    const newEntry = `dist/${filePath}`;
-    addEntry(newEntry, file);
-  });
+  /* -------------------------- Component Library (Storybook) -------------------- */
+  for (const file of glob(ComponentLibraryScssPattern)) {
+    const rel = path.relative(srcDir, file).replace(/\.scss$/, '');
+    addEntry(entries, pj('dist', 'storybook', rel), file);
+  }
 
-  return entries;
-}
+  return Object.fromEntries(entries);
+};
+
+/* -------------------------------------------------------------------------- */
+/*                              WEBPACK CONFIG EXPORT                          */
+/* -------------------------------------------------------------------------- */
 
 export default {
   target: 'web',
-  stats: {
-    errorDetails: true,
-  },
-  entry: getEntries(
-    BaseJsPattern,
-    ComponentJsPattern,
-    BaseScssPattern,
-    ComponentScssPattern,
-    ComponentLibraryScssPattern,
-    spritePattern,
-  ),
+  stats: { errorDetails: true },
+  entry: buildEntries(),
   module: {
     rules: [
       loaders.CSSLoader,
@@ -204,22 +241,26 @@ export default {
     ],
   },
   plugins: [
+    plugins.RemoveEmptyJS,
     plugins.MiniCssExtractPlugin,
     plugins.ImageminPlugin,
-    plugins.SpriteLoaderPlugin,
+    plugins.SpritePlugin,
     plugins.ProgressPlugin,
     plugins.CopyTwigPlugin,
+    plugins.CopyComponentAssetsPlugin,
+    ...(plugins.CopyGlobalAssetsPlugin ? [plugins.CopyGlobalAssetsPlugin] : []),
     plugins.CleanWebpackPlugin,
   ],
   output: {
-    path: `${projectDir}`,
+    path: projectDir,
     filename: '[name].js',
   },
   resolve: resolves.TwigResolve,
   optimization: optimizers,
+  // Quiet deprecation noise from Sass @import warnings
   ignoreWarnings: [
     (warning) =>
-      warning.message &&
+      Boolean(warning?.message) &&
       /Sass @import rules are deprecated/.test(warning.message),
   ],
 };

package/config/webpack/webpack.dev.js

@@ -27,13 +27,14 @@ const isDrupal = emulsifyConfig.project.platform === 'drupal';
 const ignored = ['**/dist/**'];
 
 // If it’s Drupal and there is no src/, also ignore components
-if (isDrupal && srcExists) {
+if (isDrupal && !srcExists) {
   ignored.push('**/components/**');
 }
 
 export default merge(common, {
   mode: 'development',
   devtool: 'source-map',
+  watch: true,
   watchOptions: {
     ignored,
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emulsify/core",
-  "version": "3.2.0",
+  "version": "3.3.1",
   "description": "Bundled tooling for Storybook development + Webpack Build",
   "keywords": [
     "component library",
@@ -72,7 +72,6 @@
     "babel-preset-minify": "^0.5.2",
     "bem-twig-extension": "^0.1.1",
     "breakpoint-sass": "^3.0.0",
-    "chalk": "^5.6.0",
     "clean-webpack-plugin": "^4.0.0",
     "concurrently": "^9.2.1",
     "copy-webpack-plugin": "^13.0.1",
@@ -108,16 +107,16 @@
     "postcss-scss": "^4.0.9",
     "ramda": "^0.31.3",
     "regenerator-runtime": "^0.14.1",
-    "sass": "^1.92.0",
+    "sass": "^1.92.1",
     "sass-loader": "^16.0.5",
     "storybook": "^8.6.14",
-    "style-dictionary": "^4.4.0",
-    "stylelint": "^16.23.1",
+    "style-dictionary": "^5.0.4",
+    "stylelint": "^16.24.0",
     "stylelint-config-standard-scss": "^15.0.1",
     "stylelint-prettier": "^5.0.3",
     "stylelint-selector-bem-pattern": "^4.0.1",
     "stylelint-webpack-plugin": "^5.0.1",
-    "svg-sprite-loader": "^6.0.11",
+    "svg-spritemap-webpack-plugin": "^5.0.1",
     "token-transformer": "^0.0.33",
     "twig-drupal-filters": "^3.2.0",
     "twig-testing-library": "^1.2.0",
@@ -125,6 +124,7 @@
     "webpack": "^5.101.3",
     "webpack-cli": "^6.0.1",
     "webpack-merge": "^6.0.1",
+    "webpack-remove-empty-scripts": "^1.1.1",
     "yaml": "^2.8.1"
   },
   "devDependencies": {
@@ -134,7 +134,7 @@
     "@semantic-release/commit-analyzer": "^13.0.1",
     "@semantic-release/git": "^10.0.1",
     "@semantic-release/github": "^11.0.5",
-    "@semantic-release/release-notes-generator": "^14.0.3",
+    "@semantic-release/release-notes-generator": "^14.1.0",
     "all-contributors-cli": "^6.26.1",
     "husky": "^9.1.7",
     "lint-staged": "^16.1.6",

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);
 }