fix: track sync-loaded files as webpack dependencies

Less's `data-uri()` built-in and any custom Less function (including
those installed via `@plugin`) load files synchronously. Webpack no
longer exposes a sync resolver, so the file manager previously signalled
`supportsSync: false` and let Less's default file manager handle the
sync read - meaning those files were never added to webpack's file
dependency set. With persistent caching enabled, changes to a file used
only via `data-uri()` would not invalidate the cached bundle.

The file manager now fulfils sync reads itself (delegating the actual
read to the parent class's `loadFile` with `syncImport: true`), records
the resolved filename as a dependency, and kicks off an async webpack
resolve in parallel so aliased / webpack-only resolutions also feed into
the dependency set. The loader awaits these tasks before completing.

Closes #492

Author: claude

src/index.js

@@ -32,7 +32,11 @@ async function lessLoader(source) {
     return;
   }
 
-  const lessOptions = getLessOptions(this, options, implementation);
+  const { lessOptions, pendingDependencyTasks } = getLessOptions(
+    this,
+    options,
+    implementation,
+  );
   const useSourceMap =
     typeof options.sourceMap === "boolean" ? options.sourceMap : this.sourceMap;
 
@@ -93,6 +97,10 @@ async function lessLoader(source) {
       this.addDependency(path.normalize(error.filename));
     }
 
+    // Wait for any pending sync-load dependency tracking so the failed
+    // build still snapshots the files it touched.
+    await Promise.all(pendingDependencyTasks);
+
     callback(errorFactory(error));
 
     return;
@@ -104,6 +112,10 @@ async function lessLoader(source) {
     delete lessOptions.pluginManager;
   }
 
+  // Ensure dependencies for any synchronously loaded resources (e.g.
+  // `data-uri()`, `@plugin`) are tracked before the loader completes.
+  await Promise.all(pendingDependencyTasks);
+
   const { css, imports } = result;
 
   for (const item of imports) {

src/utils.js

@@ -27,9 +27,14 @@ const MODULE_REQUEST_REGEX = /^[^?]*~/;
  *
  * @param {LoaderContext} loaderContext
  * @param {object} implementation
+ * @param {Array<Promise<void>>} pendingDependencyTasks
  * @returns {LessPlugin}
  */
-function createWebpackLessPlugin(loaderContext, implementation) {
+function createWebpackLessPlugin(
+  loaderContext,
+  implementation,
+  pendingDependencyTasks,
+) {
   const lessOptions = loaderContext.getOptions();
   const resolve = loaderContext.getResolve({
     dependencyType: "less",
@@ -53,13 +58,62 @@ function createWebpackLessPlugin(loaderContext, implementation) {
       return true;
     }
 
-    // Sync resolving is used at least by the `data-uri` function.
-    // This file manager doesn't know how to do it, so let's delegate it
-    // to the default file manager of Less.
-    // We could probably use loaderContext.resolveSync, but it's deprecated,
-    // see https://webpack.js.org/api/loaders/#this-resolvesync
+    // Sync loading is used by `data-uri()` and any custom Less function
+    // (including those installed via `@plugin`). Webpack doesn't expose a
+    // sync resolver, so we fulfil the sync read by delegating to Less's
+    // default file manager (which can only handle native filesystem paths)
+    // and, in parallel, kick off an async webpack resolve so the loaded
+    // file is tracked as a webpack file dependency. Without this, webpack's
+    // persistent cache won't invalidate when a sync-loaded file changes.
+    // See https://github.com/webpack/less-loader/issues/492.
     supportsSync() {
-      return false;
+      return true;
+    }
+
+    loadFileSync(filename, currentDirectory, options, environment) {
+      // The default Less `loadFileSync` internally dispatches to
+      // `this.loadFile` with `options.syncImport = true`. Because we
+      // override `loadFile` (async), dynamic dispatch would land back in
+      // our async version and break the sync contract. Invoke the parent
+      // `loadFile` directly with the sync flag instead.
+      const result = super.loadFile(
+        filename,
+        currentDirectory,
+        { ...options, syncImport: true },
+        environment,
+      );
+
+      if (result && result.filename) {
+        loaderContext.addDependency(
+          path.normalize(
+            path.isAbsolute(result.filename)
+              ? result.filename
+              : path.resolve(currentDirectory || ".", result.filename),
+          ),
+        );
+      }
+
+      // Also try to resolve via webpack so aliases / custom resolvers can
+      // contribute dependencies. The resolved content is discarded - we
+      // only need the file path to track as a dependency.
+      pendingDependencyTasks.push(
+        this.resolveFilename(filename, currentDirectory)
+          .then((resolved) => {
+            const absoluteFilename = path.isAbsolute(resolved)
+              ? resolved
+              : path.resolve(".", resolved);
+
+            loaderContext.addDependency(path.normalize(absoluteFilename));
+          })
+          .catch(() => {
+            // Webpack may legitimately fail to resolve paths that Less's
+            // default sync manager handled (e.g. node-style relative
+            // lookups). The sync result above is what Less consumes, so
+            // ignore the async failure.
+          }),
+      );
+
+      return result;
     }
 
     async resolveFilename(filename, currentDirectory) {
@@ -179,6 +233,12 @@ function getLessOptions(loaderContext, loaderOptions, implementation) {
     ...options,
   };
 
+  // Collects async dependency-resolution promises kicked off from
+  // synchronous Less file loads (e.g. `data-uri()`, `@plugin`). The loader
+  // awaits these before completing so webpack's dependency snapshot is
+  // accurate.
+  const pendingDependencyTasks = [];
+
   const plugins = [...lessOptions.plugins];
   const shouldUseWebpackImporter =
     typeof loaderOptions.webpackImporter === "boolean" ||
@@ -187,7 +247,13 @@ function getLessOptions(loaderContext, loaderOptions, implementation) {
       : true;
 
   if (shouldUseWebpackImporter) {
-    plugins.unshift(createWebpackLessPlugin(loaderContext, implementation));
+    plugins.unshift(
+      createWebpackLessPlugin(
+        loaderContext,
+        implementation,
+        pendingDependencyTasks,
+      ),
+    );
   }
 
   plugins.unshift({
@@ -200,7 +266,7 @@ function getLessOptions(loaderContext, loaderOptions, implementation) {
 
   lessOptions.plugins = plugins;
 
-  return lessOptions;
+  return { lessOptions, pendingDependencyTasks };
 }
 
 function isUnsupportedUrl(url) {

test/loader.test.js

@@ -52,6 +52,28 @@ describe("loader", { timeout: 30000 }, () => {
     t.assert.snapshot(getErrors(stats));
   });
 
+  it("should track files loaded synchronously by data-uri as dependencies", async () => {
+    const testId = "./data-uri.less";
+    const compiler = getCompiler(testId);
+    const stats = await compile(compiler);
+    const { fileDependencies } = stats.compilation;
+
+    validateDependencies(fileDependencies);
+
+    const fixtures = [
+      path.resolve(__dirname, "fixtures", "data-uri.less"),
+      path.resolve(__dirname, "fixtures", "resources", "circle.svg"),
+    ];
+
+    for (const fixture of fixtures) {
+      assert.strictEqual(
+        fileDependencies.has(fixture),
+        true,
+        `Expected ${fixture} to be tracked as a file dependency`,
+      );
+    }
+  });
+
   it("should transform urls", async (t) => {
     const testId = "./url-path.less";
     const compiler = getCompiler(testId);