stylelint-webpack-plugin 5.0.1 → 5.1.0

package/dist/linter.js

@@ -4,12 +4,12 @@ const {
   dirname,
   isAbsolute,
   join
-} = require('path');
-const StylelintError = require('./StylelintError');
-const getStylelint = require('./getStylelint');
+} = require("node:path");
+const StylelintError = require("./StylelintError");
+const getStylelintModule = require("./getStylelint");
 const {
   arrify
-} = require('./utils');
+} = require("./utils");
 
 /** @typedef {import('webpack').Compiler} Compiler */
 /** @typedef {import('webpack').Compilation} Compilation */
@@ -18,6 +18,7 @@ const {
 /** @typedef {import('./getStylelint').LinterResult} LinterResult */
 /** @typedef {import('./getStylelint').Formatter} Formatter */
 /** @typedef {import('./getStylelint').FormatterType} FormatterType */
+/** @typedef {import('./getStylelint').RuleMeta} RuleMeta */
 /** @typedef {import('./options').Options} Options */
 /** @typedef {(compilation: Compilation) => Promise<void>} GenerateReport */
 /** @typedef {{errors?: StylelintError, warnings?: StylelintError, generateReportAsset?: GenerateReport}} Report */
@@ -29,61 +30,169 @@ const {
 const resultStorage = new WeakMap();
 
 /**
- * @param {string|undefined} key
- * @param {Options} options
- * @param {Compilation} compilation
- * @returns {{lint: Linter, report: Reporter, threads: number}}
+ * @param {Compilation} compilation compilation
+ * @returns {LintResultMap} lint result map
  */
-function linter(key, options, compilation) {
-  /** @type {Stylelint} */
-  let stylelint;
+function getResultStorage({
+  compiler
+}) {
+  let storage = resultStorage.get(compiler);
+  if (!storage) {
+    resultStorage.set(compiler, storage = {});
+  }
+  return storage;
+}
 
-  /** @type {(files: string|string[]) => Promise<LintResult[]>} */
-  let lintFiles;
+/**
+ * @param {LintResult[]} results results
+ * @returns {LintResult[]} filtered results without ignored
+ */
+function removeIgnoredWarnings(results) {
+  return results.filter(result => !result.ignored);
+}
 
-  /** @type {() => Promise<void>} */
-  let cleanup;
+/**
+ * @param {Promise<LintResult[]>[]} results results
+ * @returns {Promise<LintResult[]>} flatten results
+ */
+async function flatten(results) {
+  /**
+   * @param {LintResult[]} acc acc
+   * @param {LintResult[]} list list
+   * @returns {LintResult[]} result
+   */
+  const flat = (acc, list) => [...acc, ...list];
+  return (await Promise.all(results)).reduce(flat, []);
+}
 
-  /** @type number */
-  let threads;
+/**
+ * @param {() => Promise<Stylelint>} getStylelint stylelint getter
+ * @param {FormatterType=} formatter formatter
+ * @returns {Promise<Formatter>} resolved formatter
+ */
+async function loadFormatter(getStylelint, formatter) {
+  if (typeof formatter === "function") {
+    return formatter;
+  }
+  const stylelint = await getStylelint();
+  if (typeof formatter === "string") {
+    try {
+      const fmt = stylelint.formatters[formatter];
+      // Handle both sync (v13-v15) and promise-based (v16+) formatters
+      return fmt instanceof Promise ? await fmt : fmt;
+    } catch {
+      // Load the default formatter.
+    }
+  }
+  const defaultFmt = stylelint.formatters.string;
+  // Handle both sync (v13-v15) and promise-based (v16+) formatters
+  return defaultFmt instanceof Promise ? await defaultFmt : defaultFmt;
+}
 
+/* istanbul ignore next */
+/**
+ * @param {LintResult[]} lintResults lint results
+ * @returns {{ [ruleName: string]: Partial<RuleMeta> }} a rule meta
+ */
+function getRuleMetadata(lintResults) {
+  const [lintResult] = lintResults;
+  if (lintResult === undefined) return {};
+  if (lintResult._postcssResult === undefined) return {};
+  return lintResult._postcssResult.stylelint.ruleMetadata;
+}
+
+/**
+ * @param {Formatter} formatter formatter
+ * @param {{ errors: LintResult[]; warnings: LintResult[]; }} results results
+ * @param {LinterResult} returnValue return value
+ * @returns {{ errors?: StylelintError, warnings?: StylelintError }} formatted result
+ */
+function formatResults(formatter, results, returnValue) {
+  let errors;
+  let warnings;
+  if (results.warnings.length > 0) {
+    warnings = new StylelintError(formatter(results.warnings, returnValue));
+  }
+  if (results.errors.length > 0) {
+    errors = new StylelintError(formatter(results.errors, returnValue));
+  }
+  return {
+    errors,
+    warnings
+  };
+}
+
+/**
+ * @param {Options} options options
+ * @param {LintResult[]} results results
+ * @returns {{ errors: LintResult[], warnings: LintResult[] }} parsed results
+ */
+function parseResults(options, results) {
+  /** @type {LintResult[]} */
+  const errors = [];
+
+  /** @type {LintResult[]} */
+  const warnings = [];
+  for (const file of results) {
+    const fileErrors = file.warnings.filter(message => options.emitError && message.severity === "error");
+    if (fileErrors.length > 0) {
+      errors.push({
+        ...file,
+        warnings: fileErrors
+      });
+    }
+    const fileWarnings = file.warnings.filter(message => options.emitWarning && message.severity === "warning");
+    if (fileWarnings.length > 0) {
+      warnings.push({
+        ...file,
+        warnings: fileWarnings
+      });
+    }
+  }
+  return {
+    errors,
+    warnings
+  };
+}
+
+/**
+ * @param {string | undefined} key a cache key
+ * @param {Options} options options
+ * @param {Compilation} compilation compilation
+ * @returns {{ lint: Linter, report: Reporter, threads: number }} the linter with additional functions
+ */
+function linter(key, options, compilation) {
   /** @type {Promise<LintResult[]>[]} */
   const rawResults = [];
   const crossRunResultStorage = getResultStorage(compilation);
-  try {
-    ({
-      stylelint,
-      lintFiles,
-      cleanup,
-      threads
-    } = getStylelint(key, options));
-  } catch (e) {
-    throw new StylelintError(e.message);
-  }
-  return {
-    lint,
-    report,
+  const {
+    getStylelint,
+    lintFiles,
+    cleanup,
     threads
-  };
+  } = getStylelintModule(key, options);
 
   /**
-   * @param {string | string[]} files
+   * @param {string | string[]} files files
    */
   function lint(files) {
     for (const file of arrify(files)) {
       delete crossRunResultStorage[file];
     }
-    rawResults.push(lintFiles(files).catch(e => {
-      // @ts-ignore
-      compilation.errors.push(new StylelintError(e.message));
+    rawResults.push(lintFiles(files).catch(err => {
+      compilation.errors.push(new StylelintError(err.message));
       return [];
     }));
   }
+
+  /**
+   * @returns {Promise<Report>} report
+   */
   async function report() {
     // Filter out ignored files.
     let results = removeIgnoredWarnings(
     // Get the current results, resetting the rawResults to empty
-    await flatten(rawResults.splice(0, rawResults.length)));
+    await flatten(rawResults.splice(0)));
     await cleanup();
     for (const result of results) {
       crossRunResultStorage[String(result.source)] = result;
@@ -94,15 +203,14 @@ function linter(key, options, compilation) {
     if (!results || results.length < 1) {
       return {};
     }
-    const formatter = await loadFormatter(stylelint, options.formatter);
+    const formatter = await loadFormatter(getStylelint, options.formatter);
 
     /** @type {LinterResult} */
     const returnValue = {
-      // @ts-ignore
-      cwd: options.cwd,
+      cwd: (/** @type {string} */options.cwd),
       errored: false,
       results: [],
-      output: '',
+      report: "",
       reportedDisables: [],
       ruleMetadata: getRuleMetadata(results)
     };
@@ -110,14 +218,9 @@ function linter(key, options, compilation) {
       errors,
       warnings
     } = formatResults(formatter, parseResults(options, results), returnValue);
-    return {
-      errors,
-      warnings,
-      generateReportAsset
-    };
 
     /**
-     * @param {Compilation} compilation
+     * @param {Compilation} compilation compilation
      * @returns {Promise<void>}
      */
     async function generateReportAsset({
@@ -127,10 +230,12 @@ function linter(key, options, compilation) {
         outputReport
       } = options;
       /**
-       * @param {string} name
-       * @param {string | Buffer} content
+       * @param {string} name name
+       * @param {string | Buffer} content content
+       * @returns {Promise<void>}
        */
-      const save = (name, content) => ( /** @type {Promise<void>} */
+      const save = (name, content) => (/** @type {Promise<void>} */
+
       new Promise((finish, bail) => {
         if (!compiler.outputFileSystem) return;
         const {
@@ -138,21 +243,24 @@ function linter(key, options, compilation) {
           writeFile
         } = compiler.outputFileSystem;
         // ensure directory exists
-        // @ts-ignore - the types for `outputFileSystem` are missing the 3 arg overload
         mkdir(dirname(name), {
           recursive: true
         }, err => {
           /* istanbul ignore if */
-          if (err) bail(err);else writeFile(name, content, err2 => {
-            /* istanbul ignore if */
-            if (err2) bail(err2);else finish();
-          });
+          if (err) {
+            bail(err);
+          } else {
+            writeFile(name, content, err2 => {
+              /* istanbul ignore if */
+              if (err2) bail(err2);else finish();
+            });
+          }
         });
       }));
       if (!outputReport || !outputReport.filePath) {
         return;
       }
-      const content = outputReport.formatter ? (await loadFormatter(stylelint, outputReport.formatter))(results, returnValue) : formatter(results, returnValue);
+      const content = outputReport.formatter ? (await loadFormatter(getStylelint, outputReport.formatter))(results, returnValue) : formatter(results, returnValue);
       let {
         filePath
       } = outputReport;
@@ -161,131 +269,16 @@ function linter(key, options, compilation) {
       }
       await save(filePath, String(content));
     }
-  }
-}
-
-/**
- * @param {Formatter} formatter
- * @param {{ errors: LintResult[]; warnings: LintResult[]; }} results
- * @param {LinterResult} returnValue
- * @returns {{errors?: StylelintError, warnings?: StylelintError}}
- */
-function formatResults(formatter, results, returnValue) {
-  let errors;
-  let warnings;
-  if (results.warnings.length > 0) {
-    warnings = new StylelintError(formatter(results.warnings, returnValue));
-  }
-  if (results.errors.length > 0) {
-    errors = new StylelintError(formatter(results.errors, returnValue));
+    return {
+      errors,
+      warnings,
+      generateReportAsset
+    };
   }
   return {
-    errors,
-    warnings
-  };
-}
-
-/**
- * @param {Options} options
- * @param {LintResult[]} results
- * @returns {{errors: LintResult[], warnings: LintResult[]}}
- */
-function parseResults(options, results) {
-  /** @type {LintResult[]} */
-  const errors = [];
-
-  /** @type {LintResult[]} */
-  const warnings = [];
-  results.forEach(file => {
-    const fileErrors = file.warnings.filter(message => options.emitError && message.severity === 'error');
-    if (fileErrors.length > 0) {
-      errors.push({
-        ...file,
-        warnings: fileErrors
-      });
-    }
-    const fileWarnings = file.warnings.filter(message => options.emitWarning && message.severity === 'warning');
-    if (fileWarnings.length > 0) {
-      warnings.push({
-        ...file,
-        warnings: fileWarnings
-      });
-    }
-  });
-  return {
-    errors,
-    warnings
+    lint,
+    report,
+    threads
   };
 }
-
-/**
- * @param {Stylelint} stylelint
- * @param {FormatterType=} formatter
- * @returns {Promise<Formatter>|Formatter}
- */
-function loadFormatter(stylelint, formatter) {
-  if (typeof formatter === 'function') {
-    return formatter;
-  }
-  if (typeof formatter === 'string') {
-    try {
-      return stylelint.formatters[formatter];
-    } catch (_) {
-      // Load the default formatter.
-    }
-  }
-  return stylelint.formatters.string;
-}
-
-/**
- * @param {LintResult[]} results
- * @returns {LintResult[]}
- */
-function removeIgnoredWarnings(results) {
-  return results.filter(result => !result.ignored);
-}
-
-/**
- * @param {Promise<LintResult[]>[]} results
- * @returns {Promise<LintResult[]>}
- */
-async function flatten(results) {
-  /**
-   * @param {LintResult[]} acc
-   * @param {LintResult[]} list
-   */
-  const flat = (acc, list) => [...acc, ...list];
-  return (await Promise.all(results)).reduce(flat, []);
-}
-
-/**
- * @param {Compilation} compilation
- * @returns {LintResultMap}
- */
-function getResultStorage({
-  compiler
-}) {
-  let storage = resultStorage.get(compiler);
-  if (!storage) {
-    resultStorage.set(compiler, storage = {});
-  }
-  return storage;
-}
-
-/**
- * @param {LintResult[]} lintResults
- */
-/* istanbul ignore next */
-function getRuleMetadata(lintResults) {
-  const [lintResult] = lintResults;
-
-  // eslint-disable-next-line no-undefined
-  if (lintResult === undefined) return {};
-
-  // eslint-disable-next-line no-underscore-dangle, no-undefined
-  if (lintResult._postcssResult === undefined) return {};
-
-  // eslint-disable-next-line no-underscore-dangle
-  return lintResult._postcssResult.stylelint.ruleMetadata;
-}
 module.exports = linter;

package/dist/options.js

@@ -2,47 +2,47 @@
 
 const {
   validate
-} = require('schema-utils');
-const schema = require('./options.json');
+} = require("schema-utils");
+const schema = require("./options.json");
 
 /** @typedef {import('./getStylelint').LinterOptions} StylelintOptions */
 /** @typedef {import('./getStylelint').FormatterType} FormatterType */
 
 /**
- * @typedef {Object} OutputReport
- * @property {string=} filePath
- * @property {FormatterType=} formatter
+ * @typedef {object} OutputReport
+ * @property {string=} filePath file path
+ * @property {FormatterType=} formatter formatter
  */
 
 /**
- * @typedef {Object} PluginOptions
- * @property {string} context
- * @property {boolean} emitError
- * @property {boolean} emitWarning
- * @property {string|string[]=} exclude
- * @property {string|string[]} extensions
- * @property {boolean} failOnError
- * @property {boolean} failOnWarning
- * @property {string|string[]} files
- * @property {FormatterType} formatter
- * @property {boolean} lintDirtyModulesOnly
- * @property {boolean} quiet
- * @property {string} stylelintPath
- * @property {OutputReport} outputReport
- * @property {number|boolean=} threads
+ * @typedef {object} PluginOptions
+ * @property {string} context a string indicating the root of your files
+ * @property {boolean} emitError the errors found will always be emitted
+ * @property {boolean} emitWarning the warnings found will always be emitted
+ * @property {string | string[]=} exclude specify the files and/or directories to exclude
+ * @property {string | string[]} extensions specify the extensions that should be checked
+ * @property {boolean} failOnError will cause the module build to fail if there are any errors
+ * @property {boolean} failOnWarning will cause the module build to fail if there are any warning
+ * @property {string | string[]} files specify directories, files, or globs
+ * @property {FormatterType} formatter specify the formatter you would like to use to format your results
+ * @property {boolean} lintDirtyModulesOnly lint only changed files, skip linting on start
+ * @property {boolean} quiet will process and report errors only and ignore warnings
+ * @property {string} stylelintPath path to `stylelint` instance that will be used for linting
+ * @property {OutputReport} outputReport writes the output of the errors to a file - for example, a `json` file for use for reporting
+ * @property {number | boolean=} threads number of worker threads
  */
 
 /** @typedef {Partial<PluginOptions & StylelintOptions>} Options */
 
 /**
- * @param {Options} pluginOptions
- * @returns {Partial<PluginOptions>}
+ * @param {Options} pluginOptions plugin options
+ * @returns {Partial<PluginOptions>} partial plugin options
  */
 function getOptions(pluginOptions) {
   const options = {
     cache: true,
-    cacheLocation: 'node_modules/.cache/stylelint-webpack-plugin/.stylelintcache',
-    extensions: ['css', 'scss', 'sass'],
+    cacheLocation: "node_modules/.cache/stylelint-webpack-plugin/.stylelintcache",
+    extensions: ["css", "scss", "sass"],
     emitError: true,
     emitWarning: true,
     failOnError: true,
@@ -53,17 +53,17 @@ function getOptions(pluginOptions) {
     } : {})
   };
 
-  // @ts-ignore
+  // @ts-expect-error need better types
   validate(schema, options, {
-    name: 'Stylelint Webpack Plugin',
-    baseDataPath: 'options'
+    name: "Stylelint Webpack Plugin",
+    baseDataPath: "options"
   });
   return options;
 }
 
 /**
- * @param {Options} pluginOptions
- * @returns {Partial<StylelintOptions>}
+ * @param {Options} pluginOptions plugin options
+ * @returns {Partial<StylelintOptions>} stylelint options
  */
 function getStylelintOptions(pluginOptions) {
   const stylelintOptions = {
@@ -78,9 +78,8 @@ function getStylelintOptions(pluginOptions) {
   } = schema.properties;
 
   // No need to guard the for-in because schema.properties has hardcoded keys.
-  // eslint-disable-next-line guard-for-in
   for (const option in stylelintOnlyOptions) {
-    // @ts-ignore
+    // @ts-expect-error need better types
     delete stylelintOptions[option];
   }
   return stylelintOptions;