feat: implement CircularDependencyRspackPlugin

Cargo.toml

@@ -138,6 +138,7 @@ rspack_napi_macros                     = { version = "0.2.0", path = "crates/rsp
 rspack_paths                           = { version = "0.2.0", path = "crates/rspack_paths" }
 rspack_plugin_asset                    = { version = "0.2.0", path = "crates/rspack_plugin_asset" }
 rspack_plugin_banner                   = { version = "0.2.0", path = "crates/rspack_plugin_banner" }
+rspack_plugin_circular_dependencies    = { version = "0.2.0", path = "crates/rspack_plugin_circular_dependencies" }
 rspack_plugin_context_replacement      = { version = "0.2.0", path = "crates/rspack_plugin_context_replacement" }
 rspack_plugin_copy                     = { version = "0.2.0", path = "crates/rspack_plugin_copy" }
 rspack_plugin_css                      = { version = "0.2.0", path = "crates/rspack_plugin_css" }

crates/node_binding/binding.d.ts

@@ -363,6 +363,7 @@ export declare enum BuiltinPluginName {
   LightningCssMinimizerRspackPlugin = 'LightningCssMinimizerRspackPlugin',
   BundlerInfoRspackPlugin = 'BundlerInfoRspackPlugin',
   CssExtractRspackPlugin = 'CssExtractRspackPlugin',
+  CircularDependencyRspackPlugin = 'CircularDependencyRspackPlugin',
   JsLoaderRspackPlugin = 'JsLoaderRspackPlugin',
   LazyCompilationPlugin = 'LazyCompilationPlugin'
 }
@@ -1211,6 +1212,17 @@ export interface RawCacheOptions {
   type: string
 }
 
+export interface RawCircularDependencyRspackPluginOptions {
+  failOnError?: boolean
+  allowAsyncCycles?: boolean
+  exclude?: RspackRegex
+  ignoredConnections?: Array<[ConnectionPattern, ConnectionPattern]>
+  onDetected?: (entrypoint: Module, modules: string[], compilation: Compilation) => void
+  onIgnored?: (entrypoint: Module, modules: string[], compilation: Compilation) => void
+  onStart?: (compilation: Compilation) => void
+  onEnd?: (compilation: Compilation) => void
+}
+
 export interface RawConsumeOptions {
   key: string
   import?: string

crates/rspack_binding_values/Cargo.toml

@@ -49,6 +49,7 @@ rspack_loader_swc                      = { workspace = true }
 rspack_loader_testing                  = { workspace = true }
 rspack_plugin_asset                    = { workspace = true }
 rspack_plugin_banner                   = { workspace = true }
+rspack_plugin_circular_dependencies    = { workspace = true }
 rspack_plugin_context_replacement      = { workspace = true }
 rspack_plugin_copy                     = { workspace = true }
 rspack_plugin_css                      = { workspace = true }

crates/rspack_binding_values/src/raw_options/raw_builtins/mod.rs

@@ -1,5 +1,6 @@
 mod raw_banner;
 mod raw_bundle_info;
+mod raw_circular_dependency;
 mod raw_copy;
 mod raw_css_extract;
 mod raw_dll;
@@ -29,6 +30,7 @@ use rspack_ids::{
 use rspack_napi::NapiResultExt;
 use rspack_plugin_asset::AssetPlugin;
 use rspack_plugin_banner::BannerPlugin;
+use rspack_plugin_circular_dependencies::CircularDependencyRspackPlugin;
 use rspack_plugin_context_replacement::ContextReplacementPlugin;
 use rspack_plugin_copy::{CopyRspackPlugin, CopyRspackPluginOptions};
 use rspack_plugin_css::CssPlugin;
@@ -85,6 +87,7 @@ use rspack_plugin_worker::WorkerPlugin;
 
 pub use self::{
   raw_banner::RawBannerPluginOptions,
+  raw_circular_dependency::RawCircularDependencyRspackPluginOptions,
   raw_copy::RawCopyRspackPluginOptions,
   raw_dll::{RawDllEntryPluginOptions, RawLibManifestPluginOptions},
   raw_html::RawHtmlRspackPluginOptions,
@@ -192,6 +195,7 @@ pub enum BuiltinPluginName {
   LightningCssMinimizerRspackPlugin,
   BundlerInfoRspackPlugin,
   CssExtractRspackPlugin,
+  CircularDependencyRspackPlugin,
 
   // rspack js adapter plugins
   // naming format follow XxxRspackPlugin
@@ -514,6 +518,12 @@ impl BuiltinPlugin {
         .boxed();
         plugins.push(plugin);
       }
+      BuiltinPluginName::CircularDependencyRspackPlugin => plugins.push(
+        CircularDependencyRspackPlugin::new(
+          downcast_into::<RawCircularDependencyRspackPluginOptions>(self.options)?.into(),
+        )
+        .boxed(),
+      ),
       BuiltinPluginName::JsLoaderRspackPlugin => {
         plugins
           .push(JsLoaderRspackPlugin::new(downcast_into::<JsLoaderRunner>(self.options)?).boxed());

crates/rspack_binding_values/src/raw_options/raw_builtins/raw_circular_dependency.rs

@@ -0,0 +1,105 @@
+use std::sync::Arc;
+
+use napi::{Either, JsUnknown};
+use napi_derive::napi;
+use rspack_napi::threadsafe_function::ThreadsafeFunction;
+use rspack_plugin_circular_dependencies::{
+  CircularDependencyIgnoredConnection, CircularDependencyIgnoredConnectionEntry,
+  CircularDependencyRspackPluginOptions, CompilationHookFn, CycleHandlerFn,
+};
+use rspack_regex::RspackRegex;
+
+use crate::JsCompilationWrapper;
+
+fn ignore_pattern_to_entry(
+  pattern: Either<String, RspackRegex>,
+) -> CircularDependencyIgnoredConnectionEntry {
+  match pattern {
+    Either::A(string) => CircularDependencyIgnoredConnectionEntry::String(string),
+    Either::B(pattern) => CircularDependencyIgnoredConnectionEntry::Pattern(pattern),
+  }
+}
+
+type ConnectionPattern = Either<String, RspackRegex>;
+type CycleHookParams = (String, Vec<String>, JsCompilationWrapper);
+
+#[derive(Debug)]
+#[napi(object, object_to_js = false)]
+pub struct RawCircularDependencyRspackPluginOptions {
+  pub fail_on_error: Option<bool>,
+  pub allow_async_cycles: Option<bool>,
+  pub exclude: Option<RspackRegex>,
+  pub ignored_connections: Option<Vec<(ConnectionPattern, ConnectionPattern)>>,
+  #[napi(ts_type = "(entrypoint: Module, modules: string[], compilation: Compilation) => void")]
+  pub on_detected: Option<ThreadsafeFunction<CycleHookParams, JsUnknown>>,
+  #[napi(ts_type = "(entrypoint: Module, modules: string[], compilation: Compilation) => void")]
+  pub on_ignored: Option<ThreadsafeFunction<CycleHookParams, JsUnknown>>,
+  #[napi(ts_type = "(compilation: Compilation) => void")]
+  pub on_start: Option<ThreadsafeFunction<JsCompilationWrapper, JsUnknown>>,
+  #[napi(ts_type = "(compilation: Compilation) => void")]
+  pub on_end: Option<ThreadsafeFunction<JsCompilationWrapper, JsUnknown>>,
+}
+
+impl From<RawCircularDependencyRspackPluginOptions> for CircularDependencyRspackPluginOptions {
+  fn from(value: RawCircularDependencyRspackPluginOptions) -> Self {
+    // This explicit cast is needed because Rust otherwise infers an incompatible type
+    // for the closure compared to the field in the options object.
+    let on_detected: Option<CycleHandlerFn> = match value.on_detected {
+      Some(callback) => Some(Arc::new(move |entrypoint, modules, compilation| {
+        callback.blocking_call_with_sync((
+          entrypoint,
+          modules,
+          JsCompilationWrapper::new(compilation),
+        ))?;
+        Ok(())
+      })),
+      _ => None,
+    };
+    let on_ignored: Option<CycleHandlerFn> = match value.on_ignored {
+      Some(callback) => Some(Arc::new(move |entrypoint, modules, compilation| {
+        callback.blocking_call_with_sync((
+          entrypoint,
+          modules,
+          JsCompilationWrapper::new(compilation),
+        ))?;
+        Ok(())
+      })),
+      _ => None,
+    };
+    let on_start: Option<CompilationHookFn> = match value.on_start {
+      Some(callback) => Some(Arc::new(move |compilation| {
+        callback.blocking_call_with_sync(JsCompilationWrapper::new(compilation))?;
+        Ok(())
+      })),
+      _ => None,
+    };
+    let on_end: Option<CompilationHookFn> = match value.on_end {
+      Some(callback) => Some(Arc::new(move |compilation| {
+        callback.blocking_call_with_sync(JsCompilationWrapper::new(compilation))?;
+        Ok(())
+      })),
+      _ => None,
+    };
+
+    Self {
+      fail_on_error: value.fail_on_error.unwrap_or(false),
+      allow_async_cycles: value.allow_async_cycles.unwrap_or(false),
+      exclude: value.exclude,
+      ignored_connections: value.ignored_connections.map(|connections| {
+        connections
+          .into_iter()
+          .map(|(from, to)| {
+            CircularDependencyIgnoredConnection(
+              ignore_pattern_to_entry(from),
+              ignore_pattern_to_entry(to),
+            )
+          })
+          .collect()
+      }),
+      on_detected,
+      on_ignored,
+      on_start,
+      on_end,
+    }
+  }
+}

crates/rspack_plugin_circular_dependencies/Cargo.toml

@@ -0,0 +1,20 @@
+[package]
+description = "rspack circular dependency detection plugin"
+edition     = "2021"
+license     = "MIT"
+name        = "rspack_plugin_circular_dependencies"
+repository  = "https://github.com/web-infra-dev/rspack"
+version     = "0.2.0"
+
+[dependencies]
+derive_more        = { workspace = true, features = ["debug"] }
+itertools          = { workspace = true }
+rspack_collections = { workspace = true }
+rspack_core        = { workspace = true }
+rspack_error       = { workspace = true }
+rspack_hook        = { workspace = true }
+rspack_regex       = { workspace = true }
+tracing            = { workspace = true }
+
+[package.metadata.cargo-shear]
+ignored = ["tracing"]