55
66"use strict" ;
77
8+ const HarmonyImportDependency = require ( "./dependencies/HarmonyImportDependency" ) ;
9+ const HarmonyImportSideEffectDependency = require ( "./dependencies/HarmonyImportSideEffectDependency" ) ;
810const CircularDependenciesWarning = require ( "./errors/CircularDependenciesWarning" ) ;
911const { compareModulesByIdentifier } = require ( "./util/comparators" ) ;
1012
@@ -20,6 +22,22 @@ const PLUGIN_NAME = "CircularModulesPlugin";
2022// Enough to name the worst tangles without printing the module graph.
2123const MAX_REPORTED_CYCLES = 5 ;
2224
25+ // After SideEffectsFlagPlugin / FlagDependencyUsagePlugin (stage 0).
26+ const STAGE_DETECT = 1 ;
27+
28+ /**
29+ * Bit flags for why a module is treated as circular.
30+ * A module may carry both bits when it sits in a sync SCC and is a binding-read target.
31+ * @enum {number}
32+ */
33+ const CircularKind = {
34+ None : 0 ,
35+ /** ESM binding-observable target; blocks const export inlining (TDZ). */
36+ Binding : 1 << 0 ,
37+ /** Any synchronous SCC member; blocks value binding. */
38+ Synchronous : 1 << 1
39+ } ;
40+
2341/**
2442 * The module a connection makes its origin evaluate before it can run, or
2543 * `null` when it does not: a weak reference never loads its target, and an
@@ -120,25 +138,42 @@ const formatShortestCycle = (members, moduleGraph, requestShortener) => {
120138 . join ( " -> " ) ;
121139} ;
122140
141+ /**
142+ * Whether a sync connection may observe the target's live export binding.
143+ * Bare side-effect imports do not, so their cycles stay Binding-free.
144+ * @param {ModuleGraphConnection } connection an outgoing connection
145+ * @returns {boolean } true when the dependency can read a named/default binding
146+ */
147+ const isBindingRead = ( connection ) => {
148+ const dependency = connection . dependency ;
149+ return (
150+ dependency instanceof HarmonyImportDependency &&
151+ ! ( dependency instanceof HarmonyImportSideEffectDependency )
152+ ) ;
153+ } ;
154+
123155/**
124156 * Detects circular dependencies among synchronous module imports.
125157 *
126- * Builds an adjacency layout from each module's synchronous outgoing
127- * connections (skipping weak and async-block edges), then runs an iterative
128- * SCC algorithm to find circular modules .
158+ * One sync-edge SCC pass yields Synchronous members; Binding is derived from
159+ * the same components for targets of binding-reads that share a component
160+ * (or self-import), without a second Tarjan .
129161 *
130162 * Use the static `build()` method to create an instance. All intermediate data
131163 * (adjacency layout, index mappings) is local to `build()` and released on
132164 * return. The instance only holds the result.
133165 */
134166class CycleGraph {
135167 /**
136- * @param {Set<Module> } circularModules modules in a multi-module SCC or with a self-loop (for isCircular)
168+ * @param {Set<Module> } synchronousModules sync SCC members / self-loops
169+ * @param {Set<Module> } bindingModules binding-read targets sharing a sync SCC
137170 * @param {Module[][] } circularGroups multi-module SCC groups only (for reporting; self-loops omitted)
138171 */
139- constructor ( circularModules , circularGroups ) {
172+ constructor ( synchronousModules , bindingModules , circularGroups ) {
140173 /** @type {Set<Module> } */
141- this . circularModules = circularModules ;
174+ this . synchronousModules = synchronousModules ;
175+ /** @type {Set<Module> } */
176+ this . bindingModules = bindingModules ;
142177 /** @type {Module[][] } */
143178 this . circularGroups = circularGroups ;
144179 }
@@ -149,7 +184,7 @@ class CycleGraph {
149184 * @param {Iterable<Module> } modules the set of modules
150185 * @param {ModuleGraph } moduleGraph the module graph
151186 * @param {boolean= } collectGroups also group the modules of each cycle, which
152- * only the hint reads — marking `isCircular` needs the set alone
187+ * only the hint reads — marking kinds needs the sets alone
153188 * @returns {CycleGraph } the result
154189 */
155190 static build ( modules , moduleGraph , collectGroups = false ) {
@@ -163,12 +198,16 @@ class CycleGraph {
163198 }
164199
165200 const size = moduleList . length ;
166- if ( size === 0 ) return new CycleGraph ( new Set ( ) , [ ] ) ;
201+ if ( size === 0 ) {
202+ return new CycleGraph ( new Set ( ) , new Set ( ) , [ ] ) ;
203+ }
167204
168205 /** @type {number[][] } */
169206 const edges = Array . from ( { length : size } ) ;
170207 /** @type {boolean[] } */
171208 const selfLoops = Array . from ( { length : size } , ( ) => false ) ;
209+ /** @type {[number, number][] } */
210+ const bindingReads = [ ] ;
172211
173212 for ( let i = 0 ; i < size ; i ++ ) {
174213 const module = moduleList [ i ] ;
@@ -177,23 +216,29 @@ class CycleGraph {
177216 for ( const connection of moduleGraph . getOutgoingConnections ( module ) ) {
178217 const target = getSynchronousTarget ( connection , module , moduleGraph ) ;
179218 if ( target === null ) continue ;
219+ const binding = isBindingRead ( connection ) ;
180220 if ( target === module ) {
181221 selfLoops [ i ] = true ;
222+ if ( binding ) bindingReads . push ( [ i , i ] ) ;
182223 continue ;
183224 }
184225 const targetIdx = moduleToIndex . get ( target ) ;
185226 if ( targetIdx !== undefined ) {
186227 deps . push ( targetIdx ) ;
228+ if ( binding ) bindingReads . push ( [ i , targetIdx ] ) ;
187229 }
188230 }
189231 edges [ i ] = deps ;
190232 }
191233
192234 // Iterative SCC algorithm
193235 /** @type {Set<Module> } */
194- const circularModules = new Set ( ) ;
236+ const synchronousModules = new Set ( ) ;
195237 /** @type {Module[][] } */
196238 const circularGroups = [ ] ;
239+ /** @type {Int32Array } */
240+ const componentOf = new Int32Array ( size ) . fill ( - 1 ) ;
241+ let nextComponent = 0 ;
197242 let nextIndex = 0 ;
198243 const nodeIndex = new Int32Array ( size ) . fill ( - 1 ) ;
199244 const nodeLowLink = new Int32Array ( size ) ;
@@ -246,16 +291,17 @@ class CycleGraph {
246291 w = /** @type {number } */ ( sccStack . pop ( ) ) ;
247292 nodeOnStack [ w ] = 0 ;
248293 group . push ( w ) ;
294+ componentOf [ w ] = nextComponent ;
249295 } while ( w !== v ) ;
296+ nextComponent ++ ;
250297
251298 if ( group . length > 1 || selfLoops [ v ] ) {
252299 for ( const idx of group ) {
253- circularModules . add ( moduleList [ idx ] ) ;
300+ synchronousModules . add ( moduleList [ idx ] ) ;
254301 }
255302 }
256303
257- // A module that only references itself is no cycle, so it is
258- // circular for inlining but never a group to report.
304+ // A self-loop is synchronous-circular but not a group to report.
259305 if ( collectGroups && group . length > 1 ) {
260306 circularGroups . push ( group . map ( ( idx ) => moduleList [ idx ] ) ) ;
261307 }
@@ -272,7 +318,18 @@ class CycleGraph {
272318 }
273319 }
274320
275- return new CycleGraph ( circularModules , circularGroups ) ;
321+ /** @type {Set<Module> } */
322+ const bindingModules = new Set ( ) ;
323+ for ( const [ originIdx , targetIdx ] of bindingReads ) {
324+ if (
325+ originIdx === targetIdx ||
326+ componentOf [ originIdx ] === componentOf [ targetIdx ]
327+ ) {
328+ bindingModules . add ( moduleList [ targetIdx ] ) ;
329+ }
330+ }
331+
332+ return new CycleGraph ( synchronousModules , bindingModules , circularGroups ) ;
276333 }
277334}
278335
@@ -282,7 +339,7 @@ class CycleGraph {
282339 */
283340
284341/**
285- * One SCC scan: marks isCircular on every module, and reports groups when hints are set.
342+ * One sync SCC scan: marks Synchronous and Binding kinds, reports groups when hints are set.
286343 */
287344class CircularModulesPlugin {
288345 /**
@@ -293,6 +350,32 @@ class CircularModulesPlugin {
293350 this . hints = options && options . hints ;
294351 }
295352
353+ /**
354+ * The circular kind recorded on `module.buildInfo`, or `undefined` when this
355+ * plugin did not run for the compilation.
356+ * @param {Module } module the module
357+ * @returns {number | undefined } bit flags from CircularKind
358+ */
359+ static getCircularKind ( module ) {
360+ const buildInfo = /** @type {BuildInfo | undefined } */ ( module . buildInfo ) ;
361+ if ( ! buildInfo || buildInfo . circularKind === undefined ) return undefined ;
362+ return buildInfo . circularKind ;
363+ }
364+
365+ /**
366+ * Whether the module is circular. With `kind`, requires that bit to be set.
367+ * Without `kind`, any non-None kind counts. Missing kind (plugin off) is false.
368+ * @param {Module } module the module
369+ * @param {number= } kind CircularKind bit to test (e.g. CircularKind.Binding)
370+ * @returns {boolean } true when the module matches
371+ */
372+ static isCircular ( module , kind ) {
373+ const value = CircularModulesPlugin . getCircularKind ( module ) ;
374+ if ( value === undefined ) return false ;
375+ if ( kind === undefined ) return value !== CircularKind . None ;
376+ return ( value & kind ) === kind ;
377+ }
378+
296379 /**
297380 * @param {Compiler } compiler the compiler instance
298381 * @returns {void }
@@ -304,48 +387,62 @@ class CircularModulesPlugin {
304387 /** @type {CircularDependenciesWarning | undefined } */
305388 let warning ;
306389
307- compilation . hooks . optimizeModules . tap ( PLUGIN_NAME , ( modules ) => {
308- const { circularModules, circularGroups } = CycleGraph . build (
309- modules ,
310- compilation . moduleGraph ,
311- Boolean ( hints )
312- ) ;
313-
314- // Must be an explicit boolean: ConstExportsPlugin checks `=== false`.
315- for ( const m of modules ) {
316- /** @type {BuildInfo } */
317- ( m . buildInfo ) . isCircular = circularModules . has ( m ) ;
318- }
390+ compilation . hooks . optimizeDependencies . tap (
391+ {
392+ name : PLUGIN_NAME ,
393+ stage : STAGE_DETECT
394+ } ,
395+ ( modules ) => {
396+ const { synchronousModules, bindingModules, circularGroups } =
397+ CycleGraph . build ( modules , compilation . moduleGraph , Boolean ( hints ) ) ;
398+
399+ for ( const m of modules ) {
400+ let kind = CircularKind . None ;
401+ if ( synchronousModules . has ( m ) ) {
402+ kind |= CircularKind . Synchronous ;
403+ }
404+ if ( bindingModules . has ( m ) ) {
405+ kind |= CircularKind . Binding ;
406+ }
407+ const buildInfo = /** @type {BuildInfo } */ ( m . buildInfo ) ;
408+ buildInfo . circularKind = kind ;
409+ // Kept for existing tests / readers that still check the boolean.
410+ buildInfo . isCircular = ( kind & CircularKind . Synchronous ) !== 0 ;
411+ }
319412
320- if ( ! hints ) return ;
321- if ( circularGroups . length === 0 ) return ;
322-
323- const { moduleGraph, requestShortener } = compilation ;
324-
325- // Largest tangle first; ties break by name, as the order groups are
326- // discovered in is not stable.
327- circularGroups . sort (
328- ( a , b ) =>
329- b . length - a . length ||
330- compareModulesByIdentifier (
331- getCanonicalMember ( a ) ,
332- getCanonicalMember ( b )
333- )
334- ) ;
335-
336- // The shortest cycle of a large group names two of its modules, so the
337- // size travels with it — otherwise the group reads as a pair.
338- const groups = circularGroups
339- . slice ( 0 , MAX_REPORTED_CYCLES )
340- . map ( ( members ) => ( {
341- size : members . length ,
342- cycle : formatShortestCycle ( members , moduleGraph , requestShortener )
343- } ) ) ;
344- warning = new CircularDependenciesWarning (
345- groups ,
346- circularGroups . length
347- ) ;
348- } ) ;
413+ if ( ! hints ) return ;
414+ if ( circularGroups . length === 0 ) {
415+ warning = undefined ;
416+ return ;
417+ }
418+
419+ const { moduleGraph, requestShortener } = compilation ;
420+
421+ // Largest tangle first; ties break by name, as the order groups are
422+ // discovered in is not stable.
423+ circularGroups . sort (
424+ ( a , b ) =>
425+ b . length - a . length ||
426+ compareModulesByIdentifier (
427+ getCanonicalMember ( a ) ,
428+ getCanonicalMember ( b )
429+ )
430+ ) ;
431+
432+ // The shortest cycle of a large group names two of its modules, so the
433+ // size travels with it — otherwise the group reads as a pair.
434+ const groups = circularGroups
435+ . slice ( 0 , MAX_REPORTED_CYCLES )
436+ . map ( ( members ) => ( {
437+ size : members . length ,
438+ cycle : formatShortestCycle ( members , moduleGraph , requestShortener )
439+ } ) ) ;
440+ warning = new CircularDependenciesWarning (
441+ groups ,
442+ circularGroups . length
443+ ) ;
444+ }
445+ ) ;
349446
350447 // Reported past the hash: `createHash` folds every message into it, so
351448 // a hint pushed earlier would change the build's identity.
@@ -364,4 +461,9 @@ class CircularModulesPlugin {
364461 }
365462}
366463
464+ /** @type {typeof CircularKind } */
465+ CircularModulesPlugin . CircularKind = CircularKind ;
466+ /** @type {number } */
467+ CircularModulesPlugin . STAGE_DETECT = STAGE_DETECT ;
468+
367469module . exports = CircularModulesPlugin ;
0 commit comments