perf: optimize CSS graph cycle removal (#98860)
### What? This PR changes how the graph-based CSS chunker resolves contradictory stylesheet ordering constraints. The previous implementation repeatedly found one cycle, removed one edge from it, and searched again. On dense graphs this could repeat thousands of expensive searches over almost the same data. The new implementation handles each cyclic region as a whole: 1. Compute a good global order for the modules in that region. 2. Improve that order with a small, bounded local search. 3. Remove every edge that disagrees with the chosen order in one pass. This preserves the existing chunking pipeline and its hard constraints while making cycle removal much faster. ### Why? A production reproduction contained: - 499 CSS modules - 104,473 directed ordering edges - one cyclic region containing 475 modules - 9,574 edges removed one at a time `make_acyclic` alone took **9.61 seconds**. Each removed edge caused several weighted bidirectional shortest-path searches over nearly the same dense graph. With this PR, the same reproduction spends **73.5 ms** in `make_acyclic` under full turbo-tasks tracing, approximately **131× faster** than the original measured phase. ### How does the CSS graph work? This section intentionally avoids assuming graph-theory knowledge. Suppose two routes import CSS in these orders: ```text route A: reset.css, button.css, page-a.css route B: reset.css, card.css, page-b.css ``` The chunker creates one node for each CSS file. For every ordered pair in a route, it records an arrow from the later file to the earlier file: ```text button.css → reset.css page-a.css → button.css page-a.css → reset.css ``` An arrow means “the file on the left must come after the file on the right.” If several routes agree on the same relationship, the arrow gets a larger weight. The weight is therefore a vote count: a heavier arrow represents an ordering preference supported by more routes. #### Why cycles appear Different routes can disagree: ```text route A: a.css, b.css route B: b.css, a.css ``` That creates both: ```text b.css → a.css a.css → b.css ``` There is no global order that satisfies both. This is a cycle: following the arrows eventually returns to the starting node. Before the graph can be converted into one linear CSS order, some contradictory arrows must be discarded. There is no universally correct choice in this situation because the input itself asks for mutually incompatible orders. The goal is to preserve as much heavily-supported ordering information as possible. ### Previous algorithm The previous implementation: 1. Found a short cycle using weighted bidirectional Dijkstra searches. 2. Removed the lightest edge on that cycle. 3. Repeated until no cycle remained. This makes intuitive sense for small graphs, but it is expensive when a dense cyclic region needs thousands of cuts: almost the same graph is searched again after every single removal. ### New algorithm #### 1. Find independent cyclic regions The code first finds **strongly connected components** (SCCs). An SCC is simply a group of nodes where every node can eventually reach every other node by following arrows. Only SCCs with more than one node can contain multi-node cycles. Acyclic parts of the graph are not changed. #### 2. Build a candidate order for each SCC The algorithm constructs an order using a weighted feedback-arc heuristic: - A node with no remaining prerequisites can safely go at one end. - A node that nothing else depends on can safely go at the other end. - If neither exists, choose the node whose outgoing-arrow weight most exceeds its incoming-arrow weight. Informally, place the node where it satisfies the largest net number of weighted ordering votes. Node indices break ties, so identical inputs always produce identical output. This produces a complete ordering of the SCC without deleting edges during the search. #### 3. Improve the candidate order The initial heuristic is fast but can miss simple improvements. The code therefore runs at most ten deterministic insertion sweeps: 1. Temporarily remove one node from the order. 2. Score every place where it could be inserted. 3. Move it only if the move strictly increases the total weight of satisfied arrows. Equal scores keep the existing order. The strict-improvement rule stops as soon as a sweep makes no changes; ten is only a safety limit. In a deterministic 5,000-case corpus every SCC converged within four sweeps, while the supplied reproduction converged after six. Two-node SCCs skip this refinement because their heavier direction is already the optimal choice and no non-adjacent move is possible. #### 4. Remove contradictory edges in bulk Once the SCC has an order, every arrow can be classified: - Forward arrow: agrees with the order, so keep it. - Backward arrow: contradicts the order, so remove it. After all backward arrows are removed, following arrows can never return to an earlier position. Therefore the component cannot contain a cycle. The collected petgraph edge indices are removed in descending order because petgraph uses swap-removal; descending order keeps indices that have not yet been removed valid. #### 5. Continue the existing pipeline The rest of the chunker is unchanged: - `linearize` performs a topological sort and uses original route co-occurrence data to keep frequently co-loaded modules adjacent. - `split_into_chunks` balances downloaded bytes against request cost. - Global CSS containment and maximum chunk-size constraints are still enforced downstream. ### Correctness properties The implementation preserves these hard properties: - Consistent/acyclic input graphs are unchanged. - Every multi-node SCC becomes acyclic. - Edges outside cyclic SCCs are unchanged. - Output is deterministic. - Valid production input lets `linearize` emit every CSS module. - Global CSS cannot leak into a route that did not already load it. - Maximum chunk size remains enforced. The acyclicity argument does not depend on the heuristic finding a perfect order. Any total order becomes a DAG after every backward edge is removed; the heuristic only determines which valid compromise is preferred. Production chunk groups deduplicate module ids before graph construction, so they cannot create self-loops. `make_acyclic` deliberately does not remove hand-built self-loops; that is outside the production input contract. ### Ordering quality and compatibility Conflicting route orders have no solution that satisfies every route. This PR intentionally chooses a different compromise from the previous cycle-by-cycle algorithm. Quality was evaluated on the **final order after `make_acyclic` and `linearize`**, not merely by counting graph edges that survived: | Quality check | Previous | This PR | |---|---:|---:| | Exhaustive three-module cases reaching optimum | 3,375 / 3,375 | **3,375 / 3,375** | | Satisfied observations across 5,000 random cases | 142,190 | **143,010** | | Satisfied observations in the supplied reproduction | 103,483 | **105,302** | | Reproduction chunks | 1 × 499 modules | **1 × 499 modules** | | Reproduction requests per group | 1 | **1** | On the 5,000-case corpus, ordering quality was better in 570 cases, equal in 4,388, and worse in 42. There is a measured downstream trade-off: total requests increased from 25,518 to 25,646 (**+0.50%**). Requests were better in 153 cases, equal in 4,699, and worse in 148. The implementation prioritizes aggregate import-order satisfaction while keeping that request increase bounded. Applications that accidentally depended on the previous arbitrary compromise for contradictory imports can observe a different CSS cascade. Consistent import orders are unaffected. ### Performance #### Reported reproduction and regression fixtures | Fixture | Previous | This PR | Improvement | |---|---:|---:|---:| | Supplied 499-module reproduction (full tracing) | 9.61 s | **73.5 ms** | ~131× | | Dense synthetic fixture | 2.248 s | **24.0 ms** | ~94× | | 25,600-node fragmented graph | 86.4 ms | **5.69 ms** | ~15× | Scratch arrays are reused across SCCs. The two-node fast path is important for fragmented graphs, where allocating refinement state for thousands of tiny SCCs would otherwise dominate runtime. Refinement scores candidate positions through slices and moves an accepted node with an in-place rotation, avoiding a full vector clone/removal for every node. #### Large sparse SCC comparison A second review tested a true sparse directed ring: `n` nodes, exactly `n` input edges, and one edge that must be removed. | Ring nodes | This PR | Previous | |---:|---:|---:| | 1,000 | **13.8 ms** | 103 ms | | 5,000 | **366 ms** | 2.69 s | | 10,000 | **1.47 s** | 10.87 s | | 20,000 | **5.79 s** | 50.50 s | The new algorithm is approximately 7–9× faster at every measured size on this sparse shape. #### Very large dense SCC scaling A synthetic dense fixture was also tested beyond the production reproduction's 454-node SCC: | Modules | SCC size | This PR | |---:|---:|---:| | 500 | 496 | 34 ms | | 1,000 | 1,000 | 203 ms | | 1,500 | 1,498 | 491 ms | | 2,000 | 1,999 | 1.45 s | There was no paired previous-algorithm baseline for this exact large fixture. These single-run synthetic measurements show that a sufficiently large dense SCC can still take seconds. The graph itself contains roughly a quadratic number of pairwise edges, so both graph construction and cycle resolution become expensive at that scale. Whether real applications produce single SCCs this large is unknown. A possible future mitigation is to evaluate skipping insertion refinement above a size threshold, but its ordering-quality impact has not been measured and is not part of this PR. ### Why ten refinement sweeps? The initial implementation used a maximum of three. Reviewer feedback asked whether ten would improve quality and how quickly the search normally converges, so both limits were measured with identical inputs: | Measurement | Maximum 3 | Maximum 10 | |---|---:|---:| | 5,000-case corpus satisfied observations | 310,759 | 310,759 | | 5,000-case corpus requests | 51,617 | 51,617 | | Corpus SCCs needing more than 3 sweeps | capped | 2 | | Reproduction satisfied observations | 105,300 | **105,302** | | Reproduction convergence | capped at 3 | stopped after 6 | | Reproduction full-evaluation probe | 57.4 ms | 65.8 ms | Ten was selected because three was actively truncating improvements in the reproduction, while ten allowed every measured input to stop naturally. The quality gain is intentionally described as small: +2 of 105,300 observations and no change across the random corpus. The slice/in-place refactor offsets the extra sweeps on the release fixtures (dense: 26.9 → 24.0 ms; fragmented: 6.36–6.69 → 5.69 ms). ### Verification - Focused `style_groups_graph` suite: **59 passed, 0 failed**, 2 benchmarks ignored - `cargo fmt --all -- --check` - `cargo check -p turbopack-core` - `cargo clippy -p turbopack-core --tests -- -D warnings` - CSS-order E2E: **291 passed, 0 failed**, 12 existing todos - Exhaustive three-module corpus: **3,375/3,375 optimal** - Deterministic 5,000-case corpus and supplied reproduction replay - Dense, fragmented, and sparse release performance fixtures <!-- NEXT_JS_LLM --> <!-- fleet 0ed38506-67e1-4bbf-9eab-5a809a529df4 --> --------- Co-authored-by:vercel-fleet-prod[bot] <318278635+vercel-fleet-prod[bot]@users.noreply.github.com> Co-authored-by:
Tobias Koppers <1365881+sokra@users.noreply.github.com>
Showing
This diff is collapsed.
Please
register
or
sign in
to comment