stylelint-webpack-plugin 5.0.0 → 5.1.0

package/README.md

@@ -12,9 +12,9 @@
 
 # stylelint-webpack-plugin
 
-> This version of stylelint-webpack-plugin only works with webpack 5. For the webpack 4, see the [2.x branch](https://github.com/webpack-contrib/stylelint-webpack-plugin/tree/2.x).
+> This version of `stylelint-webpack-plugin` only works with webpack 5. For webpack 4, see the [2.x branch](https://github.com/webpack/stylelint-webpack-plugin/tree/2.x).
 
-This plugin uses [`stylelint`](https://stylelint.io/) that helps you avoid errors and enforce conventions in your styles.
+This plugin uses [`stylelint`](https://stylelint.io/), which helps you avoid errors and enforce conventions in your styles.
 
 ## Getting Started
 
@@ -36,7 +36,7 @@ or
 pnpm add -D stylelint-webpack-plugin
 ```
 
-> **Note**:
+> [!NOTE]
 >
 > You also need to install `stylelint >= 13` from npm, if you haven't already:
 
@@ -56,14 +56,14 @@ or
 pnpm add -D stylelint
 ```
 
-> **Note**:
+> [!NOTE]
 >
-> If you are using Stylelint 13 rather than 14+, you might also need to install `@types/stylelint` as a dev dependency if getting stylelint related type errors.
+> If you are using Stylelint 13 rather than 14+, you might also need to install `@types/stylelint` as a dev dependency if you encounter Stylelint-related type errors.
 
-Then add the plugin to your webpack config. For example:
+Then add the plugin to your webpack configuration. For example:
 
 ```js
-const StylelintPlugin = require('stylelint-webpack-plugin');
+const StylelintPlugin = require("stylelint-webpack-plugin");
 
 module.exports = {
   // ...
@@ -74,7 +74,7 @@ module.exports = {
 
 ## Options
 
-See [stylelint's options](https://stylelint.io/user-guide/usage/node-api#options) for the complete list of options available. These options are passed through to the `stylelint` directly.
+See [stylelint's options](https://stylelint.io/user-guide/usage/node-api#options) for the complete list of available options . These options are passed directly to `stylelint`.
 
 ### `cache`
 
@@ -98,7 +98,7 @@ type cacheLocation = string;
 
 - Default: `node_modules/.cache/stylelint-webpack-plugin/.stylelintcache`
 
-Specify the path to the cache location. Can be a file or a directory.
+Specify the path to the cache location. This can be a file or a directory.
 
 ### `configFile`
 
@@ -133,7 +133,7 @@ A string indicating the root of your files.
 - Type:
 
 ```ts
-type exclude = string | Array<string>;
+type exclude = string | string[];
 ```
 
 - Default: `['node_modules', compiler.options.output.path]`
@@ -145,24 +145,24 @@ Specify the files and/or directories to exclude. Must be relative to `options.co
 - Type:
 
 ```ts
-type extensions = string | Array<string>;
+type extensions = string | string[];
 ```
 
 - Default: `['css', 'scss', 'sass']`
 
-Specify extensions that should be checked.
+Specify the extensions that should be checked.
 
 ### `files`
 
 - Type:
 
 ```ts
-type files = string | Array<string>;
+type files = string | string[];
 ```
 
 - Default: `null`
 
-Specify directories, files, or globs. Must be relative to `options.context`. Directories are traversed recursively looking for files matching `options.extensions`. File and glob patterns ignore `options.extensions`.
+Specify directories, files, or globs. Must be relative to `options.context`. Directories are traversed recursively, looking for files matching `options.extensions`. File and glob patterns ignore `options.extensions`.
 
 ### `fix`
 
@@ -181,14 +181,14 @@ If `true`, `stylelint` will fix as many errors as possible. The fixes are made t
 - Type:
 
 ```ts
-type formatter = string | (
-  results: Array<import('stylelint').LintResult>
-) => string
+type formatter =
+  | string
+  | ((results: import("stylelint").LintResult[]) => string);
 ```
 
 - Default: `'string'`
 
-Specify the formatter that you would like to use to format your results. See [formatter option](https://stylelint.io/user-guide/usage/options#formatter).
+Specify the formatter you would like to use to format your results. See the [formatter option](https://stylelint.io/user-guide/usage/options#formatter).
 
 ### `lintDirtyModulesOnly`
 
@@ -200,7 +200,7 @@ type lintDirtyModulesOnly = boolean;
 
 - Default: `false`
 
-Lint only changed files, skip lint on start.
+Lint only changed files; skip linting on start.
 
 ### `stylelintPath`
 
@@ -224,12 +224,15 @@ type threads = boolean | number;
 
 - Default: `false`
 
-Set to true for an auto-selected pool size based on number of cpus. Set to a number greater than 1 to set an explicit pool size. Set to false, 1, or less to disable and only run in main process.
+Set to `true` for an auto-selected pool size based on number of CPUs. Set to a number greater than 1 to set an explicit pool size.
+
+Set to `false`, 1, or less to disable and run only in main process.
 
 ### Errors and Warning
 
-**By default the plugin will auto adjust error reporting depending on stylelint errors/warnings counts.**
-You can still force this behavior by using `emitError` **or** `emitWarning` options:
+**By default, the plugin will automatically adjust error reporting depending on the number of Stylelint errors/warnings.**
+
+You can still force this behavior by using the `emitError` **or** `emitWarning` options:
 
 #### `emitError`
 
@@ -241,7 +244,7 @@ type emitError = boolean;
 
 - Default: `true`
 
-The errors found will always be emitted, to disable set to `false`.
+The errors found will always be emitted. To disable, set to `false`.
 
 #### `emitWarning`
 
@@ -253,7 +256,7 @@ type emitWarning = boolean;
 
 - Default: `true`
 
-The warnings found will always be emitted, to disable set to `false`.
+The warnings found will always be emitted. To disable, set to `false`.
 
 #### `failOnError`
 
@@ -265,7 +268,7 @@ type failOnError = boolean;
 
 - Default: `true`
 
-Will cause the module build to fail if there are any errors, to disable set to `false`.
+Will cause the module build to fail if there are any errors. To disable, set to `false`.
 
 #### `failOnWarning`
 
@@ -277,7 +280,7 @@ type failOnWarning = boolean;
 
 - Default: `false`
 
-Will cause the module build to fail if there are any warnings, if set to `true`.
+Will cause the module build to fail if there are any warnings, when set to `true`.
 
 #### `quiet`
 
@@ -289,7 +292,7 @@ type quiet = boolean;
 
 - Default: `false`
 
-Will process and report errors only and ignore warnings, if set to `true`.
+Will process and report errors only, and ignore warnings, when set to `true`.
 
 #### `outputReport`
 
@@ -301,31 +304,37 @@ type outputReport =
   | {
       filePath?: string | undefined;
       formatter?:
-        | (
-            | string
-            | ((results: Array<import('stylelint').LintResult>) => string)
-          )
+        | (string | ((results: import("stylelint").LintResult[]) => string))
         | undefined;
     };
 ```
 
 - Default: `false`
 
-Write the output of the errors to a file, for example a `json` file for use for reporting.
+Writes the output of the errors to a file - for example, a `json` file for use for reporting.
+
 The `filePath` is relative to the webpack config: `output.path`.
-You can pass in a different formatter for the output file, if none is passed in the default/configured formatter will be used.
+
+You can pass in a different formatter for the output file. If none is passed in the default/configured formatter will be used.
 
 ```js
-{
-  filePath: 'path/to/file';
-  formatter: 'json';
-}
+const outputReport = {
+  filePath: "path/to/file",
+  formatter: "json",
+};
 ```
 
 ## Changelog
 
 [Changelog](CHANGELOG.md)
 
+## Contributing
+
+We welcome all contributions!
+If you're new here, please take a moment to review our contributing guidelines before submitting issues or pull requests.
+
+[CONTRIBUTING](https://github.com/webpack/stylelint-webpack-plugin?tab=contributing-ov-file#contributing)
+
 ## License
 
 [MIT](./LICENSE)
@@ -334,10 +343,10 @@ You can pass in a different formatter for the output file, if none is passed in
 [npm-url]: https://npmjs.com/package/stylelint-webpack-plugin
 [node]: https://img.shields.io/node/v/stylelint-webpack-plugin.svg
 [node-url]: https://nodejs.org
-[tests]: https://github.com/webpack-contrib/stylelint-webpack-plugin/workflows/stylelint-webpack-plugin/badge.svg
-[tests-url]: https://github.com/webpack-contrib/stylelint-webpack-plugin/actions
-[cover]: https://codecov.io/gh/webpack-contrib/stylelint-webpack-plugin/branch/master/graph/badge.svg
-[cover-url]: https://codecov.io/gh/webpack-contrib/stylelint-webpack-plugin
+[tests]: https://github.com/webpack/stylelint-webpack-plugin/workflows/stylelint-webpack-plugin/badge.svg
+[tests-url]: https://github.com/webpack/stylelint-webpack-plugin/actions
+[cover]: https://codecov.io/gh/webpack/stylelint-webpack-plugin/branch/main/graph/badge.svg
+[cover-url]: https://codecov.io/gh/webpack/stylelint-webpack-plugin
 [discussion]: https://img.shields.io/github/discussions/webpack/webpack
 [discussion-url]: https://github.com/webpack/webpack/discussions
 [size]: https://packagephobia.now.sh/badge?p=stylelint-webpack-plugin

package/dist/StylelintError.js

@@ -2,12 +2,12 @@
 
 class StylelintError extends Error {
   /**
-   * @param {string=} messages
+   * @param {string=} messages messages
    */
   constructor(messages) {
     super(`[stylelint] ${messages}`);
-    this.name = 'StylelintError';
-    this.stack = '';
+    this.name = "StylelintError";
+    this.stack = "";
   }
 }
 module.exports = StylelintError;

package/dist/getStylelint.js

@@ -2,24 +2,23 @@
 
 const {
   cpus
-} = require('os');
+} = require("node:os");
 const {
   Worker: JestWorker
-} = require('jest-worker');
-
-// @ts-ignore
+} = require("jest-worker");
 const {
-  setup,
-  lintFiles
-} = require('./worker');
+  getStylelintOptions
+} = require("./options");
 const {
   jsonStringifyReplacerSortKeys
-} = require('./utils');
+} = require("./utils");
 const {
-  getStylelintOptions
-} = require('./options');
+  getStylelint: getStylelintInstance,
+  lintFiles,
+  setup
+} = require("./worker");
 
-/** @type {{[key: string]: any}} */
+/** @type {{ [key: string]: Linter }} */
 const cache = {};
 
 /** @typedef {{lint: (options: LinterOptions) => Promise<LinterResult>, formatters: { [k: string]: Formatter }}} Stylelint */
@@ -28,21 +27,22 @@ const cache = {};
 /** @typedef {import('stylelint').LinterResult} LinterResult */
 /** @typedef {import('stylelint').Formatter} Formatter */
 /** @typedef {import('stylelint').FormatterType} FormatterType */
+/** @typedef {import('stylelint').RuleMeta} RuleMeta */
 /** @typedef {import('./options').Options} Options */
 /** @typedef {() => Promise<void>} AsyncTask */
 /** @typedef {(files: string|string[]) => Promise<LintResult[]>} LintTask */
-/** @typedef {{stylelint: Stylelint, lintFiles: LintTask, cleanup: AsyncTask, threads: number }} Linter */
+/** @typedef {{getStylelint: () => Promise<Stylelint>, lintFiles: LintTask, cleanup: AsyncTask, threads: number }} Linter */
 /** @typedef {JestWorker & {lintFiles: LintTask}} Worker */
 
 /**
- * @param {Options} options
- * @returns {Linter}
+ * @param {Options} options linter options
+ * @returns {Linter} linter
  */
 function loadStylelint(options) {
   const stylelintOptions = getStylelintOptions(options);
-  const stylelint = setup(options, stylelintOptions);
+  setup(options, stylelintOptions);
   return {
-    stylelint,
+    getStylelint: getStylelintInstance,
     lintFiles,
     cleanup: async () => {},
     threads: 1
@@ -50,21 +50,34 @@ function loadStylelint(options) {
 }
 
 /**
- * @param {string|undefined} key
- * @param {number} poolSize
- * @param {Options} options
- * @returns {Linter}
+ * @param {string | undefined} key a cache key
+ * @param {Options} options options
+ * @returns {string} a stringified cache key
+ */
+function getCacheKey(key, options) {
+  return JSON.stringify({
+    key,
+    options
+  }, jsonStringifyReplacerSortKeys);
+}
+
+/**
+ * @param {string|undefined} key a cache key
+ * @param {number} poolSize number of workers
+ * @param {Options} options options
+ * @returns {Linter} linter
  */
 function loadStylelintThreaded(key, poolSize, options) {
   const cacheKey = getCacheKey(key, options);
-  const source = require.resolve('./worker');
+  const source = require.resolve("./worker");
   const workerOptions = {
     enableWorkerThreads: true,
     numWorkers: poolSize,
     setupArgs: [options, getStylelintOptions(options)]
   };
   const local = loadStylelint(options);
-  let worker = /** @type {Worker?} */new JestWorker(source, workerOptions);
+  let worker = /** @type {Worker | null} */
+  new JestWorker(source, workerOptions);
 
   /** @type {Linter} */
   const context = {
@@ -86,15 +99,15 @@ function loadStylelintThreaded(key, poolSize, options) {
 }
 
 /**
- * @param {string|undefined} key
- * @param {Options} options
- * @returns {Linter}
+ * @param {string|undefined} key a cache key
+ * @param {Options} options options
+ * @returns {Linter} linter
  */
 function getStylelint(key, {
   threads,
   ...options
 }) {
-  const max = typeof threads !== 'number' ? threads ? cpus().length - 1 : 1 : threads;
+  const max = typeof threads !== "number" ? threads ? cpus().length - 1 : 1 : threads;
   const cacheKey = getCacheKey(key, {
     threads,
     ...options
@@ -104,16 +117,4 @@ function getStylelint(key, {
   }
   return cache[cacheKey];
 }
-
-/**
- * @param {string|undefined} key
- * @param {Options} options
- * @returns {string}
- */
-function getCacheKey(key, options) {
-  return JSON.stringify({
-    key,
-    options
-  }, jsonStringifyReplacerSortKeys);
-}
 module.exports = getStylelint;

package/dist/index.js

@@ -3,31 +3,31 @@
 const {
   isAbsolute,
   join
-} = require('path');
-const globby = require('globby');
+} = require("node:path");
+const globby = require("globby");
 const {
   isMatch
-} = require('micromatch');
+} = require("micromatch");
+const linter = require("./linter");
 const {
   getOptions
-} = require('./options');
-const linter = require('./linter');
+} = require("./options");
 const {
   arrify,
   parseFiles,
   parseFoldersToGlobs
-} = require('./utils');
+} = require("./utils");
 
 /** @typedef {import('webpack').Compiler} Compiler */
 /** @typedef {import('webpack').Module} Module */
 /** @typedef {import('./options').Options} Options */
-/** @typedef {Partial<{timestamp:number} | number>} FileSystemInfoEntry */
+/** @typedef {Partial<{ timestamp:number } | number>} FileSystemInfoEntry */
 
-const STYLELINT_PLUGIN = 'StylelintWebpackPlugin';
+const STYLELINT_PLUGIN = "StylelintWebpackPlugin";
 let counter = 0;
 class StylelintWebpackPlugin {
   /**
-   * @param {Options} options
+   * @param {Options=} options options
    */
   constructor(options = {}) {
     this.key = STYLELINT_PLUGIN;
@@ -38,7 +38,7 @@ class StylelintWebpackPlugin {
   }
 
   /**
-   * @param {Compiler} compiler
+   * @param {Compiler} compiler compiler
    * @returns {void}
    */
   apply(compiler) {
@@ -46,13 +46,13 @@ class StylelintWebpackPlugin {
     // this differentiates one from the other when being cached.
     this.key = compiler.name || `${this.key}_${counter += 1}`;
     const context = this.getContext(compiler);
-    const excludeDefault = ['**/node_modules/**', String(compiler.options.output.path)];
+    const excludeDefault = ["**/node_modules/**", String(compiler.options.output.path)];
     const options = {
       ...this.options,
       context,
       exclude: parseFiles(this.options.exclude || excludeDefault, context),
       extensions: arrify(this.options.extensions),
-      files: parseFiles(this.options.files || '', context)
+      files: parseFiles(this.options.files || "", context)
     };
     const wanted = parseFoldersToGlobs(options.files, options.extensions);
     const exclude = parseFoldersToGlobs(options.exclude);
@@ -60,57 +60,39 @@ class StylelintWebpackPlugin {
     // If `lintDirtyModulesOnly` is disabled,
     // execute the linter on the build
     if (!this.options.lintDirtyModulesOnly) {
-      compiler.hooks.run.tapPromise(this.key, c => this.run(c, options, wanted, exclude));
+      compiler.hooks.run.tapPromise(this.key, compiler => this.run(compiler, options, wanted, exclude));
     }
-    let isFirstRun = this.options.lintDirtyModulesOnly;
-    compiler.hooks.watchRun.tapPromise(this.key, c => {
-      if (isFirstRun) {
-        isFirstRun = false;
+    let hasCompilerRunByDirtyModule = this.options.lintDirtyModulesOnly;
+    compiler.hooks.watchRun.tapPromise(this.key, compiler => {
+      if (hasCompilerRunByDirtyModule) {
+        hasCompilerRunByDirtyModule = false;
         return Promise.resolve();
       }
-      return this.run(c, options, wanted, exclude);
+      return this.run(compiler, options, wanted, exclude);
     });
   }
 
   /**
-   * @param {Compiler} compiler
-   * @param {Options} options
-   * @param {string[]} wanted
-   * @param {string[]} exclude
+   * @param {Compiler} compiler compiler
+   * @param {Options} options options
+   * @param {string[]} wanted wanted files
+   * @param {string[]} exclude exclude files
    */
   async run(compiler, options, wanted, exclude) {
     // Do not re-hook
-    /* istanbul ignore if */
-    if (
-    // @ts-ignore
-    compiler.hooks.thisCompilation.taps.find(({
+    const isCompilerHooked = compiler.hooks.thisCompilation.taps.find(({
       name
-    }) => name === this.key)) {
-      return;
-    }
+    }) => name === this.key);
+    if (isCompilerHooked) return;
     compiler.hooks.thisCompilation.tap(this.key, compilation => {
-      /** @type {import('./linter').Linter} */
-      let lint;
-
-      /** @type {import('./linter').Reporter} */
-      let report;
-
-      /** @type number */
-      let threads;
-      try {
-        ({
-          lint,
-          report,
-          threads
-        } = linter(this.key, options, compilation));
-      } catch (e) {
-        compilation.errors.push(e);
-        return;
-      }
+      const {
+        lint,
+        report,
+        threads
+      } = linter(this.key, options, compilation);
       compilation.hooks.finishModules.tapPromise(this.key, async () => {
         /** @type {string[]} */
-        // @ts-ignore
-        const files = compiler.modifiedFiles ? Array.from(compiler.modifiedFiles).filter(file => isMatch(file, wanted, {
+        const files = compiler.modifiedFiles ? [...compiler.modifiedFiles].filter(file => isMatch(file, wanted, {
           dot: true
         }) && !isMatch(file, exclude, {
           dot: true
@@ -127,8 +109,9 @@ class StylelintWebpackPlugin {
         }
       });
 
-      // await and interpret results
-      compilation.hooks.additionalAssets.tapPromise(this.key, processResults);
+      /**
+       * @returns {Promise<void>}
+       */
       async function processResults() {
         const {
           errors,
@@ -136,30 +119,28 @@ class StylelintWebpackPlugin {
           generateReportAsset
         } = await report();
         if (warnings && !options.failOnWarning) {
-          // @ts-ignore
           compilation.warnings.push(warnings);
         } else if (warnings && options.failOnWarning) {
-          // @ts-ignore
           compilation.errors.push(warnings);
         }
         if (errors && options.failOnError) {
-          // @ts-ignore
           compilation.errors.push(errors);
         } else if (errors && !options.failOnError) {
-          // @ts-ignore
           compilation.warnings.push(errors);
         }
         if (generateReportAsset) {
           await generateReportAsset(compilation);
         }
       }
+
+      // await and interpret results
+      compilation.hooks.additionalAssets.tapPromise(this.key, processResults);
     });
   }
 
   /**
-   *
-   * @param {Compiler} compiler
-   * @returns {string}
+   * @param {Compiler} compiler compiler
+   * @returns {string} context
    */
   getContext(compiler) {
     if (!this.options.context) {