fix(esm-library): deconflict module external helper names (#13695)

* fix(esm-library): deconflict module external helper names

* test(esm-output): cover helper-shaped node-commonjs source

* chore(esm-library): address clippy warnings

* fix(esm-library): restore init fragment helper build

* fix(esm-library): track init fragment top-level decl symbols

Author: JSerFeng

crates/rspack_core/src/external_module.rs

@@ -387,6 +387,10 @@ impl ExternalModule {
               InitFragmentKey::ModuleExternal("node-commonjs".to_string()),
               None,
             )
+            .with_top_level_decl_symbols(vec![
+              "__rspack_createRequire".into(),
+              "__rspack_createRequire_require".into(),
+            ])
             .boxed(),
           );
           let (request, specifiers) = if let Some(request) = request {

crates/rspack_core/src/init_fragment.rs

@@ -171,6 +171,10 @@ pub trait InitFragment<C>: IntoAny + DynHash + DynClone + Debug + Sync + Send {
   fn position(&self) -> i32;
 
   fn key(&self) -> &InitFragmentKey;
+
+  fn top_level_decl_symbols(&self) -> &[Atom] {
+    &[]
+  }
 }
 
 clone_trait_object!(InitFragment<GenerateContext<'_>>);
@@ -292,6 +296,7 @@ pub struct NormalInitFragment {
   position: i32,
   key: InitFragmentKey,
   end_content: Option<String>,
+  top_level_decl_symbols: Vec<Atom>,
 }
 
 impl NormalInitFragment {
@@ -308,8 +313,14 @@ impl NormalInitFragment {
       position,
       key,
       end_content,
+      top_level_decl_symbols: Vec::new(),
     }
   }
+
+  pub fn with_top_level_decl_symbols(mut self, top_level_decl_symbols: Vec<Atom>) -> Self {
+    self.top_level_decl_symbols = top_level_decl_symbols;
+    self
+  }
 }
 
 impl<C> InitFragment<C> for NormalInitFragment {
@@ -331,6 +342,10 @@ impl<C> InitFragment<C> for NormalInitFragment {
   fn key(&self) -> &InitFragmentKey {
     &self.key
   }
+
+  fn top_level_decl_symbols(&self) -> &[Atom] {
+    &self.top_level_decl_symbols
+  }
 }
 
 #[derive(Debug, Clone, Hash)]

crates/rspack_plugin_esm_library/src/link.rs

@@ -74,6 +74,72 @@ enum ExternalImportBinding {
 }
 
 impl EsmLibraryPlugin {
+  fn module_external_fragment_content(
+    init_fragment: Box<dyn rspack_core::InitFragment<ChunkRenderContext>>,
+  ) -> Option<String> {
+    if !matches!(init_fragment.key(), InitFragmentKey::ModuleExternal(_)) {
+      return None;
+    }
+
+    if let Ok(fragment) = init_fragment
+      .clone()
+      .into_any()
+      .downcast::<ConditionalInitFragment>()
+    {
+      Some(fragment.content().to_owned())
+    } else {
+      init_fragment
+        .clone()
+        .contents(&mut ChunkRenderContext {})
+        .ok()
+        .map(|contents| contents.start)
+    }
+  }
+
+  fn collect_module_external_fragments_in_render_order<'a>(
+    init_fragment_groups: impl IntoIterator<Item = &'a ChunkInitFragments>,
+  ) -> Vec<Box<dyn rspack_core::InitFragment<ChunkRenderContext>>> {
+    let mut ordered_fragments = Vec::new();
+
+    for init_fragments in init_fragment_groups {
+      for init_fragment in init_fragments {
+        if !matches!(init_fragment.key(), InitFragmentKey::ModuleExternal(_)) {
+          continue;
+        }
+
+        ordered_fragments.push((
+          init_fragment.stage(),
+          init_fragment.position(),
+          ordered_fragments.len(),
+          init_fragment.key().clone(),
+          init_fragment.clone(),
+        ));
+      }
+    }
+
+    ordered_fragments.sort_by(|a, b| {
+      let stage = a.0.cmp(&b.0);
+      if !stage.is_eq() {
+        return stage;
+      }
+      let position = a.1.cmp(&b.1);
+      if !position.is_eq() {
+        return position;
+      }
+      a.2.cmp(&b.2)
+    });
+
+    let mut rendered_keys = FxHashSet::default();
+    let mut rendered_fragments = Vec::with_capacity(ordered_fragments.len());
+    for (_, _, _, key, init_fragment) in ordered_fragments {
+      if rendered_keys.insert(key) {
+        rendered_fragments.push(init_fragment);
+      }
+    }
+
+    rendered_fragments
+  }
+
   fn parse_module_external_namespace_import(content: &str) -> Option<(RawImportSource, Atom)> {
     let content = content.trim_start();
     let content = content.strip_prefix("import * as ")?;
@@ -119,54 +185,10 @@ impl EsmLibraryPlugin {
   fn collect_module_external_namespace_imports_in_render_order<'a>(
     init_fragment_groups: impl IntoIterator<Item = &'a ChunkInitFragments>,
   ) -> Vec<(RawImportSource, Atom)> {
-    let mut ordered_imports = Vec::new();
-
-    for init_fragments in init_fragment_groups {
-      for init_fragment in init_fragments {
-        if !matches!(init_fragment.key(), InitFragmentKey::ModuleExternal(_)) {
-          continue;
-        }
-
-        let content = if let Ok(fragment) = init_fragment
-          .clone()
-          .into_any()
-          .downcast::<ConditionalInitFragment>()
-        {
-          fragment.content().to_owned()
-        } else {
-          let Ok(contents) = init_fragment.clone().contents(&mut ChunkRenderContext {}) else {
-            continue;
-          };
-          contents.start
-        };
-
-        if let Some((source, local_name)) = Self::parse_module_external_namespace_import(&content) {
-          ordered_imports.push((
-            init_fragment.stage(),
-            init_fragment.position(),
-            ordered_imports.len(),
-            source,
-            local_name,
-          ));
-        }
-      }
-    }
-
-    ordered_imports.sort_by(|a, b| {
-      let stage = a.0.cmp(&b.0);
-      if !stage.is_eq() {
-        return stage;
-      }
-      let position = a.1.cmp(&b.1);
-      if !position.is_eq() {
-        return position;
-      }
-      a.2.cmp(&b.2)
-    });
-
-    ordered_imports
+    Self::collect_module_external_fragments_in_render_order(init_fragment_groups)
       .into_iter()
-      .map(|(_, _, _, source, local_name)| (source, local_name))
+      .filter_map(Self::module_external_fragment_content)
+      .filter_map(|content| Self::parse_module_external_namespace_import(&content))
       .collect()
   }
 
@@ -191,6 +213,25 @@ impl EsmLibraryPlugin {
     }
   }
 
+  #[cfg(test)]
+  fn reserve_module_external_top_level_decls(
+    init_fragments: &ChunkInitFragments,
+    used_names: &mut FxHashSet<Atom>,
+  ) {
+    Self::reserve_module_external_top_level_decls_in_render_order([init_fragments], used_names);
+  }
+
+  fn reserve_module_external_top_level_decls_in_render_order<'a>(
+    init_fragment_groups: impl IntoIterator<Item = &'a ChunkInitFragments>,
+    used_names: &mut FxHashSet<Atom>,
+  ) {
+    for init_fragment in
+      Self::collect_module_external_fragments_in_render_order(init_fragment_groups)
+    {
+      used_names.extend(init_fragment.top_level_decl_symbols().iter().cloned());
+    }
+  }
+
   fn assign_external_candidate_name(
     readable_identifier: &str,
     candidate_used_names: &mut FxHashSet<Atom>,
@@ -971,10 +1012,14 @@ var {} = {{}};
       }
     }
     Self::reserve_module_external_namespace_import_locals_in_render_order(
-      module_external_init_fragment_groups,
+      module_external_init_fragment_groups.iter().copied(),
       &mut all_used_names,
       Some(&mut chunk_link.module_external_namespace_imports),
     );
+    Self::reserve_module_external_top_level_decls_in_render_order(
+      module_external_init_fragment_groups.iter().copied(),
+      &mut all_used_names,
+    );
 
     // deconflict top level symbols
     for id in chunk_link
@@ -3572,6 +3617,95 @@ mod tests {
     assert!(chunk_used_names.is_empty());
   }
 
+  #[test]
+  fn module_external_non_namespace_init_fragment_claims_top_level_decls() {
+    let init_fragments: ChunkInitFragments = vec![Box::new(rspack_core::NormalInitFragment::new(
+      "import { createRequire as __rspack_createRequire } from \"node:module\";\nconst __rspack_createRequire_require = __rspack_createRequire(import.meta.url);\n"
+        .into(),
+      rspack_core::InitFragmentStage::StageESMImports,
+      0,
+      InitFragmentKey::ModuleExternal("node-commonjs".into()),
+      None,
+    )
+    .with_top_level_decl_symbols(vec![
+      "__rspack_createRequire".into(),
+      "__rspack_createRequire_require".into(),
+    ]))];
+    let mut chunk_used_names = FxHashSet::default();
+
+    EsmLibraryPlugin::reserve_module_external_top_level_decls(
+      &init_fragments,
+      &mut chunk_used_names,
+    );
+
+    assert!(chunk_used_names.contains(&Atom::from("__rspack_createRequire")));
+    assert!(chunk_used_names.contains(&Atom::from("__rspack_createRequire_require")));
+  }
+
+  #[test]
+  fn module_external_top_level_decls_keep_first_rendered_fragment() {
+    let init_fragments: ChunkInitFragments = vec![
+      Box::new(rspack_core::NormalInitFragment::new(
+        "import { createRequire as __rspack_createRequire_1 } from \"node:module\";\nconst __rspack_createRequire_require_1 = __rspack_createRequire_1(import.meta.url);\n"
+          .into(),
+        rspack_core::InitFragmentStage::StageESMImports,
+        1,
+        InitFragmentKey::ModuleExternal("node-commonjs".into()),
+        None,
+      )
+      .with_top_level_decl_symbols(vec![
+        "__rspack_createRequire_1".into(),
+        "__rspack_createRequire_require_1".into(),
+      ])),
+      Box::new(rspack_core::NormalInitFragment::new(
+        "import { createRequire as __rspack_createRequire_0 } from \"node:module\";\nconst __rspack_createRequire_require_0 = __rspack_createRequire_0(import.meta.url);\n"
+          .into(),
+        rspack_core::InitFragmentStage::StageESMImports,
+        0,
+        InitFragmentKey::ModuleExternal("node-commonjs".into()),
+        None,
+      )
+      .with_top_level_decl_symbols(vec![
+        "__rspack_createRequire_0".into(),
+        "__rspack_createRequire_require_0".into(),
+      ])),
+    ];
+    let mut chunk_used_names = FxHashSet::default();
+
+    EsmLibraryPlugin::reserve_module_external_top_level_decls(
+      &init_fragments,
+      &mut chunk_used_names,
+    );
+
+    assert!(chunk_used_names.contains(&Atom::from("__rspack_createRequire_0")));
+    assert!(chunk_used_names.contains(&Atom::from("__rspack_createRequire_require_0")));
+    assert!(!chunk_used_names.contains(&Atom::from("__rspack_createRequire_1")));
+    assert!(!chunk_used_names.contains(&Atom::from("__rspack_createRequire_require_1")));
+  }
+
+  #[test]
+  fn module_external_var_init_fragment_claims_top_level_decl() {
+    let init_fragments: ChunkInitFragments = vec![Box::new(
+      rspack_core::NormalInitFragment::new(
+        "/* provided dependency */ var provided_identifier = __webpack_require__(\"./dep\");\n"
+          .into(),
+        rspack_core::InitFragmentStage::StageProvides,
+        1,
+        InitFragmentKey::ModuleExternal("provided provided_identifier".into()),
+        None,
+      )
+      .with_top_level_decl_symbols(vec!["provided_identifier".into()]),
+    )];
+    let mut chunk_used_names = FxHashSet::default();
+
+    EsmLibraryPlugin::reserve_module_external_top_level_decls(
+      &init_fragments,
+      &mut chunk_used_names,
+    );
+
+    assert!(chunk_used_names.contains(&Atom::from("provided_identifier")));
+  }
+
   #[test]
   fn external_candidate_name_does_not_claim_chunk_top_level_name() {
     let module = ModuleIdentifier::from("test_module");

crates/rspack_plugin_javascript/src/dependency/esm/provide_dependency.rs

@@ -194,18 +194,21 @@ impl DependencyTemplate for ProvideDependencyTemplate {
       )
     };
 
-    init_fragments.push(Box::new(NormalInitFragment::new(
-      format!(
-        "/* provided dependency */ var {} = {}{};\n",
-        dep.identifier,
-        runtime_template.module_raw(compilation, dep.id(), dep.request(), dep.weak()),
-        path_to_string(used_name.as_ref())
-      ),
-      InitFragmentStage::StageProvides,
-      1,
-      InitFragmentKey::ModuleExternal(format!("provided {}", dep.identifier)),
-      None,
-    )));
+    init_fragments.push(Box::new(
+      NormalInitFragment::new(
+        format!(
+          "/* provided dependency */ var {} = {}{};\n",
+          dep.identifier,
+          runtime_template.module_raw(compilation, dep.id(), dep.request(), dep.weak()),
+          path_to_string(used_name.as_ref())
+        ),
+        InitFragmentStage::StageProvides,
+        1,
+        InitFragmentKey::ModuleExternal(format!("provided {}", dep.identifier)),
+        None,
+      )
+      .with_top_level_decl_symbols(vec![dep.identifier.clone().into()]),
+    ));
     source.replace(dep.range.start, dep.range.end, dep.identifier.clone(), None);
   }
 }

crates/rspack_plugin_javascript/src/plugin/api_plugin.rs

@@ -61,6 +61,10 @@ async fn render_module_content(
         InitFragmentKey::ModuleExternal("node-commonjs".to_string()),
         None,
       )
+      .with_top_level_decl_symbols(vec![
+        "__rspack_createRequire".into(),
+        "__rspack_createRequire_require".into(),
+      ])
       .boxed(),
     );
   }