fix(template-webpack-plugin): make getLynxTemplatePluginHooks a cross-module singleton

.changeset/template-plugin-hooks-singleton.md

@@ -0,0 +1,5 @@
+---
+"@lynx-js/template-webpack-plugin": patch
+---
+
+Make `LynxTemplatePlugin.getLynxTemplatePluginHooks` a cross-module singleton so duplicate copies of this package (e.g. from npm hoist conflicts) share the same hooks per compilation.

packages/webpack/template-webpack-plugin/src/LynxTemplatePlugin.ts

@@ -56,7 +56,11 @@ export interface EncodeOptions {
   [k: string]: unknown;
 }
 
-const LynxTemplatePluginHooksMap = new WeakMap<Compilation, TemplateHooks>();
+// Use `Symbol.for` so duplicate copies of this module (e.g. from an npm hoist
+// conflict that nests two copies under node_modules) share the same hooks slot.
+const LYNX_TEMPLATE_HOOKS_KEY: unique symbol = Symbol.for(
+  '@lynx-js/template-webpack-plugin/hooks',
+) as never;
 
 /**
  * To allow other plugins to alter the Template, this plugin executes
@@ -352,13 +356,14 @@ export class LynxTemplatePlugin {
    * Returns all public hooks of the Lynx template webpack plugin for the given compilation
    */
   static getLynxTemplatePluginHooks(compilation: Compilation): TemplateHooks {
-    let hooks = LynxTemplatePluginHooksMap.get(compilation);
+    const stash = compilation as unknown as {
+      [LYNX_TEMPLATE_HOOKS_KEY]?: TemplateHooks;
+    };
+    let hooks = stash[LYNX_TEMPLATE_HOOKS_KEY];
     // Setup the hooks only once
     if (hooks === undefined) {
-      LynxTemplatePluginHooksMap.set(
-        compilation,
-        hooks = createLynxTemplatePluginHooks(),
-      );
+      hooks = createLynxTemplatePluginHooks();
+      stash[LYNX_TEMPLATE_HOOKS_KEY] = hooks;
     }
     return hooks;
   }

packages/webpack/template-webpack-plugin/test/fixtures/template-plugin-second-instance.ts

@@ -0,0 +1,49 @@
+// Copyright 2024 The Lynx Authors. All rights reserved.
+// Licensed under the Apache License Version 2.0 that can be found in the
+// LICENSE file in the root directory of this source tree.
+
+// Mimics a second physical copy of `@lynx-js/template-webpack-plugin` that
+// would land at a separate node_modules path under npm hoist conflicts. It
+// re-implements `getLynxTemplatePluginHooks` end-to-end so that *this* module
+// instance has its own `createHooks` and its own module-level state — any
+// successful cross-instance sharing must therefore happen through whatever
+// shared slot the real implementation uses on `compilation`, not through
+// accidental code identity.
+import {
+  AsyncSeriesBailHook,
+  AsyncSeriesWaterfallHook,
+  SyncWaterfallHook,
+} from '@rspack/lite-tapable';
+
+const LYNX_TEMPLATE_HOOKS_KEY = Symbol.for(
+  '@lynx-js/template-webpack-plugin/hooks',
+);
+
+interface MinimalHooks {
+  asyncChunkName: SyncWaterfallHook<unknown>;
+  beforeEncode: AsyncSeriesWaterfallHook<unknown>;
+  encode: AsyncSeriesBailHook<unknown, unknown>;
+  beforeEmit: AsyncSeriesWaterfallHook<unknown>;
+  afterEmit: AsyncSeriesWaterfallHook<unknown>;
+}
+
+function createHooks(): MinimalHooks {
+  return {
+    asyncChunkName: new SyncWaterfallHook(['pluginArgs']),
+    beforeEncode: new AsyncSeriesWaterfallHook(['pluginArgs']),
+    encode: new AsyncSeriesBailHook(['pluginArgs']),
+    beforeEmit: new AsyncSeriesWaterfallHook(['pluginArgs']),
+    afterEmit: new AsyncSeriesWaterfallHook(['pluginArgs']),
+  };
+}
+
+export function getHooksFromSecondInstance(
+  compilation: Record<symbol, unknown>,
+): MinimalHooks {
+  let hooks = compilation[LYNX_TEMPLATE_HOOKS_KEY] as MinimalHooks | undefined;
+  if (hooks === undefined) {
+    hooks = createHooks();
+    compilation[LYNX_TEMPLATE_HOOKS_KEY] = hooks;
+  }
+  return hooks;
+}

packages/webpack/template-webpack-plugin/test/get-hooks-singleton.test.ts

@@ -0,0 +1,65 @@
+// Copyright 2024 The Lynx Authors. All rights reserved.
+// Licensed under the Apache License Version 2.0 that can be found in the
+// LICENSE file in the root directory of this source tree.
+import { describe, expect, test } from '@rstest/core';
+
+import { LynxTemplatePlugin } from '../src/index.js';
+import { getHooksFromSecondInstance } from './fixtures/template-plugin-second-instance.js';
+
+describe('LynxTemplatePlugin.getLynxTemplatePluginHooks - cross-module singleton', () => {
+  test('returns the same hooks for the same compilation across calls', () => {
+    const compilation = {} as never;
+    const a = LynxTemplatePlugin.getLynxTemplatePluginHooks(compilation);
+    const b = LynxTemplatePlugin.getLynxTemplatePluginHooks(compilation);
+    expect(b).toBe(a);
+  });
+
+  test('returns distinct hooks for distinct compilations', () => {
+    const compilationA = {} as never;
+    const compilationB = {} as never;
+    const a = LynxTemplatePlugin.getLynxTemplatePluginHooks(compilationA);
+    const b = LynxTemplatePlugin.getLynxTemplatePluginHooks(compilationB);
+    expect(a).not.toBe(b);
+  });
+
+  test('real instance writes first, second physical copy reads the same hooks', () => {
+    const compilation = {} as Record<symbol, unknown>;
+    const hooksReal = LynxTemplatePlugin
+      .getLynxTemplatePluginHooks(compilation as never);
+    const hooksSecond = getHooksFromSecondInstance(compilation);
+    expect(hooksSecond).toBe(hooksReal);
+  });
+
+  test('second physical copy writes first, real instance reads the same hooks', () => {
+    const compilation = {} as Record<symbol, unknown>;
+    const hooksSecond = getHooksFromSecondInstance(compilation);
+    const hooksReal = LynxTemplatePlugin
+      .getLynxTemplatePluginHooks(compilation as never);
+    expect(hooksReal).toBe(hooksSecond);
+  });
+
+  test('a tap registered through one copy fires when encode.promise is awaited through the other', async () => {
+    const compilation = {} as Record<symbol, unknown>;
+    const hooksReal = LynxTemplatePlugin
+      .getLynxTemplatePluginHooks(compilation as never);
+
+    const sentinel = {
+      buffer: Buffer.from('ok'),
+      debugInfo: '',
+      cssDiagnostics: '',
+    };
+    hooksReal.encode.tapPromise(
+      { name: 'tap-from-real-instance', stage: 0 },
+      async () => sentinel,
+    );
+
+    const hooksSecond = getHooksFromSecondInstance(compilation);
+    const result = await (hooksSecond.encode as unknown as {
+      promise: (args: unknown) => Promise<unknown>;
+    }).promise({
+      encodeOptions: {},
+      intermediate: '.rspeedy',
+    });
+    expect(result).toBe(sentinel);
+  });
+});