sass-loader 16.0.8 → 17.0.0

package/dist/{utils.js → cjs/utils.js}

@@ -8,58 +8,145 @@ exports.getCompileFn = getCompileFn;
 exports.getModernWebpackImporter = getModernWebpackImporter;
 exports.getSassImplementation = getSassImplementation;
 exports.getSassOptions = getSassOptions;
-exports.getWebpackImporter = getWebpackImporter;
 exports.getWebpackResolver = getWebpackResolver;
 exports.normalizeSourceMap = normalizeSourceMap;
 var _nodePath = _interopRequireDefault(require("node:path"));
 var _nodeUrl = _interopRequireDefault(require("node:url"));
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
-/** @typedef {import("sass")} Sass */
-/** @typedef {import("sass").StringOptionsWithImporter} SassSassOptions */
-/** @typedef {import("sass-embedded")} SassEmbedded */
-/** @typedef {import("sass-embedded").StringOptionsWithImporter} SassEmbeddedOptions */
+// eslint-disable-next-line jsdoc/reject-any-type
+/** @typedef {any} EXPECTED_ANY */
 
-/** @typedef {Sass | SassEmbedded} SassImplementation */
-/** @typedef {SassSassOptions | SassEmbeddedOptions} SassOptions */
-// eslint-disable-next-line jsdoc/no-restricted-syntax
-/** @typedef {Record<string, any>} LoaderOptions */
+/**
+ * @typedef {object} SourceLocation
+ * @property {number} line line number
+ * @property {number} column column number
+ * @property {number} offset character offset
+ */
 
 /**
- * @returns {Sass | SassEmbedded} sass implementation
+ * @typedef {object} SourceSpan
+ * @property {SourceLocation} start start location
+ * @property {SourceLocation} end end location
+ * @property {URL=} url canonical URL of the file
+ * @property {string} text covered text
+ * @property {string=} context surrounding context
  */
-function getDefaultSassImplementation() {
-  let sassImplPkg = "sass";
-  try {
-    require.resolve("sass-embedded");
-    sassImplPkg = "sass-embedded";
-  } catch {
-    try {
-      require.resolve("sass");
-    } catch {
-      try {
-        require.resolve("node-sass");
-        sassImplPkg = "node-sass";
-      } catch {
-        sassImplPkg = "sass";
-      }
-    }
+
+/** @typedef {{ deprecation?: boolean, span?: SourceSpan, stack?: string }} LoggerWarnOptions */
+
+/**
+ * @typedef {object} Logger
+ * @property {((message: string, options: LoggerWarnOptions) => void)=} warn warn handler
+ * @property {((message: string, options: { span: SourceSpan }) => void)=} debug debug handler
+ */
+
+/**
+ * @typedef {object} CompileResult
+ * @property {Buffer | string} css css output
+ * @property {RawSourceMap=} sourceMap source map
+ * @property {URL[]} loadedUrls loaded URLs
+ */
+
+/**
+ * @typedef {object} Importer
+ * @property {(originalUrl: string, context: { containingUrl: URL | null, fromImport: boolean }) => Promise<URL | null>} canonicalize canonicalize
+ * @property {(canonicalUrl: URL) => Promise<{ contents: string, syntax: "scss" | "indented" | "css", sourceMapUrl?: URL } | null>} load load
+ */
+
+/** @typedef {"expanded" | "compressed"} OutputStyle */
+
+/**
+ * @typedef {object} KnownSassOptions
+ * @property {"scss" | "indented" | "css"=} syntax syntax
+ * @property {URL=} url url
+ * @property {"expanded" | "compressed"=} style style
+ * @property {string[]=} loadPaths load paths
+ * @property {boolean=} sourceMap source map
+ * @property {boolean=} sourceMapIncludeSources source map include sources
+ * @property {Importer[]=} importers importers
+ * @property {Logger=} logger logger
+ */
+
+/** @typedef {KnownSassOptions & Record<string, EXPECTED_ANY>} SassOptions */
+
+/**
+ * @typedef {object} AsyncCompiler
+ * @property {(source: string, options?: SassOptions) => Promise<CompileResult>} compileStringAsync compile a string
+ * @property {() => Promise<void>} dispose dispose the compiler
+ */
+
+/** @typedef {{ info: string; compileStringAsync(source: string, options?: SassOptions): Promise<CompileResult>; initAsyncCompiler?(): Promise<AsyncCompiler> }} SassImplementation */
+
+/** @typedef {"auto" | "modern" | "modern-compiler"} ApiType */
+
+/** @typedef {import("webpack").LoaderContext<LoaderOptions>} LoaderContext */
+
+/**
+ * @typedef {object} LoaderOptions
+ * @property {SassImplementation=} implementation SaSS implementation
+ * @property {SassOptions | ((loaderContext: LoaderContext) => SassOptions)=} sassOptions SaSS options
+ * @property {boolean=} sourceMap true if source map is enabled, otherwise false
+ * @property {string | ((content: string, loaderContext: LoaderContext) => string)=} additionalData prepends Sass/SCSS code before the actual entry file
+ * @property {boolean=} webpackImporter true if webpack importer is enabled, otherwise false
+ * @property {ApiType=} api API type
+ * @property {boolean=} warnRuleAsWarning true if treats the `@warn` rule as a webpack warning, otherwise false
+ */
+
+/** @typedef {(context: string, request: string, fromImport?: boolean) => Promise<string>} Resolver */
+/** @typedef {{ resolve: (context: string, request: string) => Promise<string>, context: string, possibleRequests: string[] }[]} ResolutionMap */
+/** @typedef {{ version: number, sources: string[], names: string[], sourceRoot?: string, sourcesContent?: string[], mappings: string, file: string, debugId?: string, ignoreList?: number[] }} RawSourceMap */
+/** @typedef {Error & { formatted?: string, span?: { url?: URL, start: { line: number, column: number }, context?: string } }} SassError */
+
+/**
+ * Convert a string `implementation` option into something the ECMAScript
+ * `import()` expression actually accepts. Bare package specifiers and
+ * `file:` URLs are passed through unchanged; absolute filesystem paths
+ * (including Windows paths like `C:\\...`) are converted to `file:` URLs
+ * — dynamic `import()` rejects those otherwise.
+ * @param {string} specifier import specifier
+ * @returns {string} a valid dynamic import specifier
+ */
+function normalizeImportSpecifier(specifier) {
+  if (specifier.startsWith("file:")) {
+    return specifier;
   }
-  return require(sassImplPkg);
+  if (_nodePath.default.isAbsolute(specifier)) {
+    return _nodeUrl.default.pathToFileURL(specifier).href;
+  }
+  return specifier;
 }
 
 /**
  * This function is not Webpack-specific and can be used by tools wishing to mimic `sass-loader`'s behaviour, so its signature should not be changed.
- * @param {LoaderContext} loaderContext loader context
- * @param {SassImplementation} implementation sass implementation
- * @returns {SassImplementation} resolved sass implementation
+ * @param {SassImplementation | string | undefined} implementation sass implementation
+ * @returns {Promise<SassImplementation>} resolved sass implementation
  */
-function getSassImplementation(loaderContext, implementation) {
-  let resolvedImplementation = implementation;
-  if (!resolvedImplementation) {
-    resolvedImplementation = getDefaultSassImplementation();
-  }
-  if (typeof resolvedImplementation === "string") {
-    resolvedImplementation = require(resolvedImplementation);
+async function getSassImplementation(implementation) {
+  /** @type {SassImplementation} */
+  let resolvedImplementation;
+  if (!implementation) {
+    try {
+      resolvedImplementation = /** @type {SassImplementation} */
+      await import("sass-embedded");
+    } catch (err) {
+      // Only fall back to `sass` when `sass-embedded` is not installed.
+      // Any other failure (e.g. a broken install or a side-effect throw at
+      // module-load time) should surface so the user can diagnose it
+      // instead of being silently masked by the `sass` fallback.
+      const {
+        code
+      } = /** @type {NodeJS.ErrnoException} */err;
+      if (code !== "ERR_MODULE_NOT_FOUND" && code !== "MODULE_NOT_FOUND") {
+        throw err;
+      }
+      resolvedImplementation = /** @type {SassImplementation} */
+      await import("sass");
+    }
+  } else if (typeof implementation === "string") {
+    resolvedImplementation = /** @type {SassImplementation} */
+    await import(normalizeImportSpecifier(implementation));
+  } else {
+    resolvedImplementation = implementation;
   }
   const {
     info
@@ -74,8 +161,6 @@ function getSassImplementation(loaderContext, implementation) {
   const [implementationName] = infoParts;
   if (implementationName === "dart-sass") {
     return resolvedImplementation;
-  } else if (implementationName === "node-sass") {
-    return resolvedImplementation;
   } else if (implementationName === "sass-embedded") {
     return resolvedImplementation;
   }
@@ -90,33 +175,18 @@ function isProductionLikeMode(loaderContext) {
   return loaderContext.mode === "production" || !loaderContext.mode;
 }
 
-/**
- * @param {Importer[]} importers importers
- * @param {LoaderContext} loaderContext loader context
- * @returns {Importer[]} proxied importers
- */
-function proxyCustomImporters(importers, loaderContext) {
-  return [importers].flat().map(importer => function proxyImporter(...args) {
-    const self = {
-      ...this,
-      webpackLoaderContext: loaderContext
-    };
-    return importer.apply(self, args);
-  });
-}
-
 /**
  * Derives the sass options from the loader context and normalizes its values with sane defaults.
  * @param {LoaderContext} loaderContext loader context
  * @param {LoaderOptions} loaderOptions loader options
  * @param {string} content content
- * @param {SassImplementation} implementation sass implementation
  * @param {boolean} useSourceMap true when need to generate source maps, otherwise false
- * @param {"legacy" | "modern" | "modern-compiler"} apiType api type
- * @returns {SassOptions} sass options
+ * @returns {Promise<Required<KnownSassOptions> & { data: string }>} sass options
  */
-async function getSassOptions(loaderContext, loaderOptions, content, implementation, useSourceMap, apiType) {
+async function getSassOptions(loaderContext, loaderOptions, content, useSourceMap) {
+  /** @type {SassOptions} */
   const options = loaderOptions.sassOptions ? typeof loaderOptions.sassOptions === "function" ? loaderOptions.sassOptions(loaderContext) || {} : loaderOptions.sassOptions : {};
+  /** @type {KnownSassOptions & { data: string }} */
   const sassOptions = {
     ...options,
     data: loaderOptions.additionalData ? typeof loaderOptions.additionalData === "function" ? await loaderOptions.additionalData(content, loaderContext) : `${loaderOptions.additionalData}\n${content}` : content
@@ -124,9 +194,22 @@ async function getSassOptions(loaderContext, loaderOptions, content, implementat
   if (!sassOptions.logger) {
     const needEmitWarning = loaderOptions.warnRuleAsWarning !== false;
     const logger = loaderContext.getLogger("sass-loader");
+    /**
+     * @param {SourceSpan} span span
+     * @returns {string} formatted span
+     */
     const formatSpan = span => `Warning on line ${span.start.line}, column ${span.start.column} of ${span.url || "-"}:${span.start.line}:${span.start.column}:\n`;
+    /**
+     * @param {SourceSpan} span span
+     * @returns {string} formatted debug span
+     */
     const formatDebugSpan = span => `[debug:${span.start.line}:${span.start.column}] `;
     sassOptions.logger = {
+      /**
+       * @param {string} message message
+       * @param {{ span: SourceSpan }} loggerOptions logger options
+       * @returns {void}
+       */
       debug(message, loggerOptions) {
         let builtMessage = "";
         if (loggerOptions.span) {
@@ -135,6 +218,11 @@ async function getSassOptions(loaderContext, loaderOptions, content, implementat
         builtMessage += message;
         logger.debug(builtMessage);
       },
+      /**
+       * @param {string} message message
+       * @param {LoggerWarnOptions} loggerOptions logger options
+       * @returns {void}
+       */
       warn(message, loggerOptions) {
         let builtMessage = "";
         if (loggerOptions.deprecation) {
@@ -153,7 +241,7 @@ async function getSassOptions(loaderContext, loaderOptions, content, implementat
         if (needEmitWarning) {
           const warning = new Error(builtMessage);
           warning.name = "SassWarning";
-          warning.stack = null;
+          warning.stack = undefined;
           loaderContext.emitWarning(warning);
         } else {
           logger.warn(builtMessage);
@@ -161,81 +249,36 @@ async function getSassOptions(loaderContext, loaderOptions, content, implementat
       }
     };
   }
-  const isModernAPI = apiType === "modern" || apiType === "modern-compiler";
   const {
     resourcePath
   } = loaderContext;
-  if (isModernAPI) {
-    sassOptions.url = _nodeUrl.default.pathToFileURL(resourcePath);
+  sassOptions.url = _nodeUrl.default.pathToFileURL(resourcePath);
 
-    // opt.outputStyle
-    if (!sassOptions.style && isProductionLikeMode(loaderContext)) {
-      sassOptions.style = "compressed";
-    }
-    if (useSourceMap) {
-      sassOptions.sourceMap = true;
-      sassOptions.sourceMapIncludeSources = true;
-    }
-
-    // If we are compiling sass and indentedSyntax isn't set, automatically set it.
-    if (typeof sassOptions.syntax === "undefined") {
-      const ext = _nodePath.default.extname(resourcePath);
-      if (ext && ext.toLowerCase() === ".scss") {
-        sassOptions.syntax = "scss";
-      } else if (ext && ext.toLowerCase() === ".sass") {
-        sassOptions.syntax = "indented";
-      } else if (ext && ext.toLowerCase() === ".css") {
-        sassOptions.syntax = "css";
-      }
-    }
-    sassOptions.loadPaths = [
-    // We use `loadPaths` in context for resolver, so it should be always absolute
-    ...(sassOptions.loadPaths ? [...sassOptions.loadPaths] : []).map(includePath => _nodePath.default.isAbsolute(includePath) ? includePath : _nodePath.default.join(process.cwd(), includePath)), ...(process.env.SASS_PATH ? process.env.SASS_PATH.split(process.platform === "win32" ? ";" : ":") : [])];
-    sassOptions.importers = sassOptions.importers ? Array.isArray(sassOptions.importers) ? [...sassOptions.importers] : [sassOptions.importers] : [];
-  } else {
-    sassOptions.file = resourcePath;
+  // opt.outputStyle
+  if (!sassOptions.style && isProductionLikeMode(loaderContext)) {
+    sassOptions.style = "compressed";
+  }
+  if (useSourceMap) {
+    sassOptions.sourceMap = true;
+    sassOptions.sourceMapIncludeSources = true;
+  }
 
-    // opt.outputStyle
-    if (!sassOptions.outputStyle && isProductionLikeMode(loaderContext)) {
-      sassOptions.outputStyle = "compressed";
-    }
-    if (useSourceMap) {
-      // Deliberately overriding the sourceMap option here.
-      // node-sass won't produce source maps if the data option is used and options.sourceMap is not a string.
-      // In case it is a string, options.sourceMap should be a path where the source map is written.
-      // But since we're using the data option, the source map will not actually be written, but
-      // all paths in sourceMap.sources will be relative to that path.
-      // Pretty complicated... :(
-      sassOptions.sourceMap = true;
-      sassOptions.outFile = _nodePath.default.join(loaderContext.rootContext, "style.css.map");
-      sassOptions.sourceMapContents = true;
-      sassOptions.omitSourceMapUrl = true;
-      sassOptions.sourceMapEmbed = false;
-    }
+  // If we are compiling sass and indentedSyntax isn't set, automatically set it.
+  if (typeof sassOptions.syntax === "undefined") {
     const ext = _nodePath.default.extname(resourcePath);
-
-    // If we are compiling sass and indentedSyntax isn't set, automatically set it.
-    if (ext && ext.toLowerCase() === ".sass" && typeof sassOptions.indentedSyntax === "undefined") {
-      sassOptions.indentedSyntax = true;
-    } else {
-      sassOptions.indentedSyntax = Boolean(sassOptions.indentedSyntax);
-    }
-
-    // Allow passing custom importers to `sass`/`node-sass`. Accepts `Function` or an array of `Function`s.
-    sassOptions.importer = sassOptions.importer ? proxyCustomImporters(Array.isArray(sassOptions.importer) ? [...sassOptions.importer] : [sassOptions.importer], loaderContext) : [];
-
-    // Regression on the `sass-embedded` side
-    if (loaderOptions.webpackImporter === false && sassOptions.importer.length === 0) {
-      sassOptions.importer = undefined;
-    }
-    sassOptions.includePaths = [process.cwd(), ...
-    // We use `includePaths` in context for resolver, so it should be always absolute
-    (sassOptions.includePaths ? [...sassOptions.includePaths] : []).map(includePath => _nodePath.default.isAbsolute(includePath) ? includePath : _nodePath.default.join(process.cwd(), includePath)), ...(process.env.SASS_PATH ? process.env.SASS_PATH.split(process.platform === "win32" ? ";" : ":") : [])];
-    if (typeof sassOptions.charset === "undefined") {
-      sassOptions.charset = true;
+    if (ext && ext.toLowerCase() === ".scss") {
+      sassOptions.syntax = "scss";
+    } else if (ext && ext.toLowerCase() === ".sass") {
+      sassOptions.syntax = "indented";
+    } else if (ext && ext.toLowerCase() === ".css") {
+      sassOptions.syntax = "css";
     }
   }
-  return sassOptions;
+  sassOptions.loadPaths = [
+  // We use `loadPaths` in context for resolver, so it should be always absolute
+  ...(sassOptions.loadPaths ? [...sassOptions.loadPaths] : []).map(includePath => _nodePath.default.isAbsolute(includePath) ? includePath : _nodePath.default.join(process.cwd(), includePath)), ...(process.env.SASS_PATH ? process.env.SASS_PATH.split(process.platform === "win32" ? ";" : ":") : [])];
+  sassOptions.importers = sassOptions.importers ? Array.isArray(sassOptions.importers) ? [...sassOptions.importers] : [sassOptions.importers] : [];
+  return /** @type {Required<KnownSassOptions> & { data: string }} */sassOptions;
 }
 const MODULE_REQUEST_REGEX = /^[^?]*~/;
 
@@ -250,7 +293,7 @@ const IS_MODULE_IMPORT = /^~([^/]+|[^/]+\/|@[^/]+[/][^/]+|@[^/]+\/?|@[^/]+[/][^/
 const IS_PKG_SCHEME = /^pkg:/i;
 
 /**
- * When `sass`/`node-sass` tries to resolve an import, it uses a special algorithm.
+ * When `sass` tries to resolve an import, it uses a special algorithm.
  * Since the `sass-loader` uses webpack to resolve the modules, we need to simulate that algorithm.
  * This function returns an array of import paths to try.
  * The last entry in the array is always the original url to enable straight-forward webpack.config aliases.
@@ -291,8 +334,7 @@ function getPossibleRequests(url, forWebpackResolver = false, fromImport = false
   //  - imports where the URL is written as a url().
   //  - imports that have media queries.
   //
-  // The `node-sass` package sends `@import` ending on `.css` to importer, it is bug, so we skip resolve
-  // Also sass outputs as is `@import "style.css"`, but `@use "style.css"` should include CSS content
+  // sass outputs as is `@import "style.css"`, but `@use "style.css"` should include CSS content
   if (extension === ".css") {
     return fromImport ? [] : [url];
   }
@@ -349,7 +391,7 @@ async function startResolving(resolutionMap) {
     return startResolving(resolutionMap);
   }
 }
-const IS_SPECIAL_MODULE_IMPORT = /^~[^/]+$/;
+
 // `[drive_letter]:\` + `\\[server]\[sharename]\`
 const IS_NATIVE_WIN32_PATH = /^[a-z]:[/\\]|^\\\\/i;
 
@@ -359,14 +401,10 @@ const IS_NATIVE_WIN32_PATH = /^[a-z]:[/\\]|^\\\\/i;
  * in a Jest transform. Such usages will want to wrap `resolve.create` from
  * [`enhanced-resolve`]{@link https://github.com/webpack/enhanced-resolve} to
  * pass as the `resolverFactory` argument.
- * @param {ResolveFactory} resolverFactory a factory function for creating a Webpack resolver.
- * @param {Sass} implementation the imported Sass implementation, both `sass` (Dart Sass) and `node-sass` are supported.
- * @param {string[]=} includePaths the list of include paths passed to Sass.
+ * @param {LoaderContext["getResolve"]} resolverFactory a factory function for creating a Webpack resolver.
  * @returns {Resolver} webpack resolver
- * @throws If a compatible Sass implementation cannot be found.
  */
-function getWebpackResolver(resolverFactory, implementation, includePaths = []) {
-  const isModernSass = implementation && typeof implementation.compileStringAsync !== "undefined";
+function getWebpackResolver(resolverFactory) {
   // We only have one difference with the built-in sass resolution logic and out resolution logic:
   // First, we look at the files starting with `_`, then without `_` (i.e. `_name.sass`, `_name.scss`, `_name.css`, `name.sass`, `name.scss`, `name.css`),
   // although `sass` look together by extensions (i.e. `_name.sass`/`name.sass`/`_name.scss`/`name.scss`/`_name.css`/`name.css`).
@@ -375,32 +413,6 @@ function getWebpackResolver(resolverFactory, implementation, includePaths = [])
   // - on having `_name.sass` and `_name.scss` in the same directory
   //
   // Also `sass` prefer `sass`/`scss` over `css`.
-  const sassModuleResolve = promiseResolve(resolverFactory({
-    alias: [],
-    aliasFields: [],
-    conditionNames: [],
-    descriptionFiles: [],
-    extensions: [".sass", ".scss", ".css"],
-    exportsFields: [],
-    mainFields: [],
-    mainFiles: ["_index", "index"],
-    modules: [],
-    restrictions: [/\.((sa|sc|c)ss)$/i],
-    preferRelative: true
-  }));
-  const sassImportResolve = promiseResolve(resolverFactory({
-    alias: [],
-    aliasFields: [],
-    conditionNames: [],
-    descriptionFiles: [],
-    extensions: [".sass", ".scss", ".css"],
-    exportsFields: [],
-    mainFields: [],
-    mainFiles: ["_index.import", "_index", "index.import", "index"],
-    modules: [],
-    restrictions: [/\.((sa|sc|c)ss)$/i],
-    preferRelative: true
-  }));
   const webpackModuleResolve = promiseResolve(resolverFactory({
     dependencyType: "sass",
     conditionNames: ["sass", "style", "..."],
@@ -420,12 +432,6 @@ function getWebpackResolver(resolverFactory, implementation, includePaths = [])
     preferRelative: true
   }));
   return (context, request, fromImport) => {
-    // See https://github.com/webpack/webpack/issues/12340
-    // Because `node-sass` calls our importer before `1. Filesystem imports relative to the base file.`
-    // custom importer may not return `{ file: '/path/to/name.ext' }` and therefore our `context` will be relative
-    if (!isModernSass && !_nodePath.default.isAbsolute(context)) {
-      return Promise.reject();
-    }
     const originalRequest = request;
     const isFileScheme = originalRequest.slice(0, 5).toLowerCase() === "file:";
     if (isFileScheme) {
@@ -435,43 +441,9 @@ function getWebpackResolver(resolverFactory, implementation, includePaths = [])
         request = request.slice(7);
       }
     }
+
+    /** @type {ResolutionMap} */
     let resolutionMap = [];
-    const needEmulateSassResolver =
-    // `sass` doesn't support module import
-    !IS_SPECIAL_MODULE_IMPORT.test(request) &&
-    // don't handle `pkg:` scheme
-    !IS_PKG_SCHEME.test(request) &&
-    // We need improve absolute paths handling.
-    // Absolute paths should be resolved:
-    // - Server-relative URLs - `<context>/path/to/file.ext` (where `<context>` is root context)
-    // - Absolute path - `/full/path/to/file.ext` or `C:\\full\path\to\file.ext`
-    !isFileScheme && !originalRequest.startsWith("/") && !IS_NATIVE_WIN32_PATH.test(originalRequest);
-    if (includePaths.length > 0 && needEmulateSassResolver) {
-      // The order of import precedence is as follows:
-      //
-      // 1. Filesystem imports relative to the base file.
-      // 2. Custom importer imports.
-      // 3. Filesystem imports relative to the working directory.
-      // 4. Filesystem imports relative to an `includePaths` path.
-      // 5. Filesystem imports relative to a `SASS_PATH` path.
-      //
-      // `sass` run custom importers before `3`, `4` and `5` points, we need to emulate this behavior to avoid wrong resolution.
-      const sassPossibleRequests = getPossibleRequests(request, false, fromImport);
-
-      // `node-sass` calls our importer before `1. Filesystem imports relative to the base file.`, so we need emulate this too
-      if (!isModernSass) {
-        resolutionMap = [...resolutionMap, {
-          resolve: fromImport ? sassImportResolve : sassModuleResolve,
-          context: _nodePath.default.dirname(context),
-          possibleRequests: sassPossibleRequests
-        }];
-      }
-      resolutionMap = [...resolutionMap, ...includePaths.map(context => ({
-        resolve: fromImport ? sassImportResolve : sassModuleResolve,
-        context,
-        possibleRequests: sassPossibleRequests
-      }))];
-    }
     const webpackPossibleRequests = getPossibleRequests(request, true, fromImport);
     resolutionMap = [...resolutionMap, {
       resolve: fromImport ? webpackImportResolve : webpackModuleResolve,
@@ -481,17 +453,19 @@ function getWebpackResolver(resolverFactory, implementation, includePaths = [])
     return startResolving(resolutionMap);
   };
 }
-const MATCH_CSS = /\.css$/i;
 
 /**
  * @param {LoaderContext} loaderContext loader context
- * @param {SassImplementation} implementation sass implementation
- * @param {string[]} loadPaths load paths
  * @returns {Importer} the modern webpack importer
  */
-function getModernWebpackImporter(loaderContext, implementation, loadPaths) {
-  const resolve = getWebpackResolver(loaderContext.getResolve, implementation, loadPaths);
+function getModernWebpackImporter(loaderContext) {
+  const resolve = getWebpackResolver(loaderContext.getResolve);
   return {
+    /**
+     * @param {string} originalUrl original url
+     * @param {{ fromImport: boolean, containingUrl: URL | null }} context context
+     * @returns {Promise<URL | null>} canonicalized URL
+     */
     async canonicalize(originalUrl, context) {
       const {
         fromImport
@@ -507,8 +481,14 @@ function getModernWebpackImporter(loaderContext, implementation, loadPaths) {
       loaderContext.addDependency(_nodePath.default.normalize(result));
       return _nodeUrl.default.pathToFileURL(result);
     },
+    /**
+     * @param {URL} canonicalUrl canonical url
+     * @returns {Promise<{ contents: string, syntax: "scss" | "indented" | "css", sourceMapUrl: URL } | null>} load result
+     */
     async load(canonicalUrl) {
       const ext = _nodePath.default.extname(canonicalUrl.pathname);
+
+      /** @type {"scss" | "indented" | "css"} */
       let syntax;
       if (ext && ext.toLowerCase() === ".scss") {
         syntax = "scss";
@@ -521,12 +501,19 @@ function getModernWebpackImporter(loaderContext, implementation, loadPaths) {
         syntax = "scss";
       }
       try {
-        const contents = await new Promise((resolve, reject) => {
+        const contents = /** @type {string} */
+        await new Promise((resolve, reject) => {
           // Old version of `enhanced-resolve` supports only path as a string
           // TODO simplify in the next major release and pass URL
           const canonicalPath = _nodeUrl.default.fileURLToPath(canonicalUrl);
-          loaderContext.fs.readFile(canonicalPath, (err, content) => {
-            if (err) {
+          loaderContext.fs.readFile(canonicalPath,
+          /**
+           * @param {NodeJS.ErrnoException | null} err error
+           * @param {Buffer | undefined} content content
+           * @returns {void}
+           */
+          (err, content) => {
+            if (err || !content) {
               reject(err);
               return;
             }
@@ -545,132 +532,67 @@ function getModernWebpackImporter(loaderContext, implementation, loadPaths) {
   };
 }
 
-/**
- * @param {LoaderContext} loaderContext loader context
- * @param {SassImplementation} implementation sass implementation
- * @param {string[]} includePaths include paths
- * @returns {Importer} the webpack importer
- */
-function getWebpackImporter(loaderContext, implementation, includePaths) {
-  const resolve = getWebpackResolver(loaderContext.getResolve, implementation, includePaths);
-  return function importer(originalUrl, prev, done) {
-    const {
-      fromImport
-    } = this;
-    resolve(prev, originalUrl,
-    // For `node-sass`
-    typeof fromImport === "undefined" ? true : fromImport).then(result => {
-      // Add the result as dependency.
-      // Although we're also using stats.includedFiles, this might come in handy when an error occurs.
-      // In this case, we don't get stats.includedFiles from node-sass/sass.
-      loaderContext.addDependency(_nodePath.default.normalize(result));
-
-      // By removing the CSS file extension, we trigger node-sass to include the CSS file instead of just linking it.
-      done({
-        file: result.replace(MATCH_CSS, "")
-      });
-    })
-    // Catch all resolving errors, return the original file and pass responsibility back to other custom importers
-    .catch(() => {
-      done({
-        file: originalUrl
-      });
-    });
-  };
-}
-let nodeSassJobQueue = null;
+/** @type {WeakMap<import("webpack").Compiler, AsyncCompiler>} */
 const sassModernCompilers = new WeakMap();
 
 /**
  * Verifies that the implementation and version of Sass is supported by this loader.
+ * @template {SassImplementation} T
  * @param {LoaderContext} loaderContext loader context
- * @param {SassImplementation} implementation sass implementation
- * @param {"legacy" | "modern" | "modern-compiler"} apiType api type
- * @returns {SassCompileFunction} compile function
+ * @param {T} implementation sass implementation
+ * @param {ApiType=} apiType api type
+ * @returns {(sassOptions: SassOptions & { data: string }) => Promise<CompileResult>} compile function
  */
-function getCompileFn(loaderContext, implementation, apiType) {
-  if (typeof implementation.compileStringAsync !== "undefined") {
-    if (apiType === "modern") {
-      return sassOptions => {
-        const {
-          data,
-          ...rest
-        } = sassOptions;
-        return implementation.compileStringAsync(data, rest);
-      };
-    }
-    if (apiType === "modern-compiler") {
-      return async sassOptions => {
-        const webpackCompiler = loaderContext._compiler;
-        const {
-          data,
-          ...rest
-        } = sassOptions;
-
-        // Some people can run the loader in a multi-threading way;
-        // there is no webpack compiler object in such case.
-        if (webpackCompiler) {
+function getCompileFn(loaderContext, implementation, apiType = "auto") {
+  const {
+    initAsyncCompiler
+  } = implementation;
+  if (apiType === "modern-compiler" || apiType === "auto" && typeof initAsyncCompiler === "function") {
+    return async (/** @type {SassOptions & { data: string }} */sassOptions) => {
+      const webpackCompiler = /** @type {LoaderContext & { _compiler?: import("webpack").Compiler }} */
+      loaderContext._compiler;
+      const {
+        data,
+        ...rest
+      } = sassOptions;
+
+      // Some people can run the loader in a multi-threading way;
+      // there is no webpack compiler object in such case.
+      if (webpackCompiler && initAsyncCompiler) {
+        if (!sassModernCompilers.has(webpackCompiler)) {
+          // Create a long-running compiler process that can be reused
+          // for compiling individual files.
+          const compiler = await initAsyncCompiler();
+
+          // Check again because awaiting the initialization function
+          // introduces a race condition.
           if (!sassModernCompilers.has(webpackCompiler)) {
-            // Create a long-running compiler process that can be reused
-            // for compiling individual files.
-            const compiler = await implementation.initAsyncCompiler();
-
-            // Check again because awaiting the initialization function
-            // introduces a race condition.
-            if (!sassModernCompilers.has(webpackCompiler)) {
-              sassModernCompilers.set(webpackCompiler, compiler);
-              webpackCompiler.hooks.shutdown.tap("sass-loader", () => {
-                compiler.dispose();
-              });
-            } else {
+            sassModernCompilers.set(webpackCompiler, compiler);
+            webpackCompiler.hooks.shutdown.tap("sass-loader", () => {
               compiler.dispose();
-            }
+            });
+          } else {
+            compiler.dispose();
           }
-          return sassModernCompilers.get(webpackCompiler).compileStringAsync(data, rest);
         }
-        return implementation.compileStringAsync(data, rest);
-      };
-    }
-    return sassOptions => new Promise((resolve, reject) => {
-      implementation.render(sassOptions, (error, result) => {
-        if (error) {
-          reject(error);
-          return;
-        }
-        resolve(result);
-      });
-    });
-  }
-  if (apiType === "modern" || apiType === "modern-compiler") {
-    throw new Error("Modern API is not supported for 'node-sass'");
-  }
-
-  // There is an issue with node-sass when async custom importers are used
-  // See https://github.com/sass/node-sass/issues/857#issuecomment-93594360
-  // We need to use a job queue to make sure that one thread is always available to the UV lib
-  if (nodeSassJobQueue === null) {
-    const threadPoolSize = Number(process.env.UV_THREADPOOL_SIZE || 4);
-
-    // Only used for `node-sass`, so let's load it lazily
-
-    const async = require("neo-async");
-    nodeSassJobQueue = async.queue(implementation.render.bind(implementation), threadPoolSize - 1);
-  }
-  return sassOptions => new Promise((resolve, reject) => {
-    nodeSassJobQueue.push.bind(nodeSassJobQueue)(sassOptions, (error, result) => {
-      if (error) {
-        reject(error);
-        return;
+        return /** @type {AsyncCompiler} */sassModernCompilers.get(webpackCompiler).compileStringAsync(/** @type {string} */data, rest);
       }
-      resolve(result);
-    });
-  });
+      return implementation.compileStringAsync(/** @type {string} */data, rest);
+    };
+  }
+  return (/** @type {SassOptions & { data: string }} */sassOptions) => {
+    const {
+      data,
+      ...rest
+    } = sassOptions;
+    return implementation.compileStringAsync(/** @type {string} */data, rest);
+  };
 }
 const ABSOLUTE_SCHEME = /^[A-Za-z0-9+\-.]+:/;
 
 /**
  * @param {string} source source
- * @returns {"absolute" | "scheme-relative" | "path-absolute" | "path-absolute"} a type of URL
+ * @returns {"absolute" | "scheme-relative" | "path-absolute" | "path-relative"} a type of URL
  */
 function getURLType(source) {
   if (source[0] === "/") {
@@ -697,15 +619,16 @@ function normalizeSourceMap(map, rootContext) {
   // Since we don't know the final filename in the webpack build chain yet, it makes no sense to have it.
 
   if (typeof newMap.file !== "undefined") {
+    // @ts-expect-error need to fix on webpack side
     delete newMap.file;
   }
   newMap.sourceRoot = "";
 
-  // node-sass returns POSIX paths, that's why we need to transform them back to native paths.
+  // sass returns POSIX paths, that's why we need to transform them back to native paths.
   // This fixes an error on windows where the source-map module cannot resolve the source maps.
   // @see https://github.com/webpack/sass-loader/issues/366#issuecomment-279460722
 
-  newMap.sources = newMap.sources.map(source => {
+  newMap.sources = newMap.sources.map((/** @type {string} */source) => {
     const sourceType = getURLType(source);
 
     // Do no touch `scheme-relative`, `path-absolute` and `absolute` types (except `file:`)
@@ -724,11 +647,12 @@ function normalizeSourceMap(map, rootContext) {
  * @returns {Error} a new error
  */
 function errorFactory(error) {
-  const message = error.formatted ? error.formatted.replace(/^(.+)?Error: /, "") : (error.message || error.toString()).replace(/^(.+)?Error: /, "");
+  const sassError = /** @type {SassError} */error;
+  const message = sassError.formatted ? sassError.formatted.replace(/^(.+)?Error: /, "") : (error.message || error.toString()).replace(/^(.+)?Error: /, "");
   const obj = new Error(message, {
     cause: error
   });
   obj.name = error.name;
-  obj.stack = null;
+  obj.stack = undefined;
   return obj;
 }