feat(hot): include the changed file in the building event (#2352)

The compiler's invalid hook reports which file invalidated the
compilation. Forward it as an optional `file` field on the `building`
payload and log it in the client, so users can see what triggered a
rebuild.

Ref webpack/webpack-hot-middleware#173

Author: bjohansebas

client-src/index.js

@@ -205,7 +205,7 @@ export function disconnect() {
 // eslint-disable-next-line jsdoc/reject-any-type
 /** @typedef {any} EXPECTED_ANY */
 
-/** @typedef {{ name?: string, errors: string[], warnings: string[], hash: string, time?: number, action?: string }} HMRPayload */
+/** @typedef {{ name?: string, errors: string[], warnings: string[], hash: string, time?: number, action?: string, file?: string }} HMRPayload */
 
 /**
  * @returns {{
@@ -291,7 +291,11 @@ let subscribeAllHandler;
 function processMessage(obj) {
   switch (obj.action) {
     case "building": {
-      log.info(`bundle ${obj.name ? `'${obj.name}' ` : ""}rebuilding`);
+      log.info(
+        `bundle ${obj.name ? `'${obj.name}' ` : ""}rebuilding${
+          obj.file ? ` (${obj.file} changed)` : ""
+        }`,
+      );
       break;
     }
     case "built":

src/hot.js

@@ -20,6 +20,7 @@
 /**
  * @typedef {object} Payload
  * @property {string} action action
+ * @property {string=} file file that invalidated the compilation
  * @property {string=} name name
  * @property {number=} time time
  * @property {string=} hash hash
@@ -262,12 +263,22 @@ function createHot(compiler, userOptions) {
   let latestStats = null;
   let closed = false;
 
-  const onInvalid = () => {
+  /** @param {string | null=} fileName file that triggered the rebuild */
+  const onInvalid = (fileName) => {
     if (closed) return;
 
     latestStats = null;
 
-    eventStream.publish({ action: "building" });
+    /** @type {{ action: string, file?: string }} */
+    const payload = { action: "building" };
+
+    // The invalid hook reports which file changed — forward it so clients
+    // can show what triggered the rebuild.
+    if (typeof fileName === "string" && fileName) {
+      payload.file = fileName;
+    }
+
+    eventStream.publish(payload);
   };
 
   /** @param {Stats | MultiStats} statsResult stats result */

test/client.test.js

@@ -159,6 +159,17 @@ describe("client", () => {
       expect(processUpdate).toHaveBeenCalledTimes(1);
     });
 
+    it("logs the changed file on building messages", () => {
+      EventSourceStub.lastInstance().onmessage(
+        makeMessage({ action: "building", file: "/src/index.js" }),
+      );
+      expect(
+        console.info.mock.calls.some(([msg]) =>
+          msg.includes("rebuilding (/src/index.js changed)"),
+        ),
+      ).toBe(true);
+    });
+
     it("calls subscribeAll handler on default messages", () => {
       const spy = jest.fn();
       client.subscribeAll(spy);

test/helpers/sse.js

@@ -3,6 +3,7 @@ import http from "node:http";
 /**
  * @typedef {object} SseEvent
  * @property {string=} action event action (building/built/sync/custom)
+ * @property {string=} file file that invalidated the compilation
  * @property {string=} name compilation name
  * @property {string=} hash compilation hash
  * @property {number=} time build time in ms

test/hot.test.js

@@ -27,8 +27,8 @@ function makeFakeCompiler(logger = noopLogger) {
       done: { tap: (_name, fn) => doneTaps.push(fn) },
     },
     getInfrastructureLogger: () => logger,
-    emitInvalid() {
-      for (const fn of invalidTaps) fn();
+    emitInvalid(fileName) {
+      for (const fn of invalidTaps) fn(fileName);
     },
     emitDone(stats) {
       for (const fn of doneTaps) fn(stats);
@@ -315,6 +315,38 @@ describe("createHot", () => {
     hot.close();
   });
 
+  it("includes the changed file in the building payload", () => {
+    const compiler = makeFakeCompiler();
+    const hot = createHot(compiler, {});
+    const { writes } = attachClient({ handler: hot.handle });
+
+    compiler.emitInvalid("/src/index.js");
+
+    expect(
+      writes.some(
+        (w) =>
+          w.includes('"action":"building"') &&
+          w.includes('"file":"/src/index.js"'),
+      ),
+    ).toBe(true);
+
+    hot.close();
+  });
+
+  it("omits the file field when the invalid hook reports none", () => {
+    const compiler = makeFakeCompiler();
+    const hot = createHot(compiler, {});
+    const { writes } = attachClient({ handler: hot.handle });
+
+    compiler.emitInvalid();
+
+    const building = writes.find((w) => w.includes('"action":"building"'));
+    expect(building).toBeDefined();
+    expect(building).not.toContain('"file"');
+
+    hot.close();
+  });
+
   it("sends a sync payload to a client that connects after a build", () => {
     const compiler = makeFakeCompiler();
     const hot = createHot(compiler, {});

types/hot.d.ts

@@ -60,6 +60,7 @@ declare const HOT_DEFAULT_HEARTBEAT: number;
 /**
  * @typedef {object} Payload
  * @property {string} action action
+ * @property {string=} file file that invalidated the compilation
  * @property {string=} name name
  * @property {number=} time time
  * @property {string=} hash hash
@@ -158,6 +159,10 @@ type Payload = {
    * action
    */
   action: string;
+  /**
+   * file that invalidated the compilation
+   */
+  file?: string | undefined;
   /**
    * name
    */