Turbopack: add TURBOPACK_DEBUG_CSS_CHUNKING env var (#95080)
### What?
Adds a `TURBOPACK_DEBUG_CSS_CHUNKING` environment variable. When set to
a truthy value, the graph-based CSS chunker (`experimental.cssChunking:
"graph"`) writes a JSON snapshot of its inputs and outputs to the
current working directory on each invocation.
### Why?
We are investigating problems with the new graph-based CSS chunking
algorithm. The pipeline (`create_graph` → `make_acyclic` → `linearize` →
`split_into_chunks`) is internal to `turbopack-core` and doesn't surface
enough information through normal build output to debug bad chunking
decisions post-hoc. A side-channel dump lets us reproduce and reason
about a problematic build without instrumenting Rust on a user's
machine.
### How?
In
`turbopack/crates/turbopack-core/src/module_graph/style_groups_graph/mod.rs`,
between `split_into_chunks` and the result assembly:
- Whether the dump is enabled is cached in a `static DEBUG_DUMP_ENABLED:
LazyLock<bool>` so the env var is read exactly once per process. Truthy
= anything other than unset, empty, `0`, or `false` (case-insensitive).
- When enabled, every call to `compute_style_groups_graph` resolves
`ident_string()` for every CSS module in parallel via `try_join` and
writes a pretty-printed JSON file
`turbopack-css-chunking-debug-<unix_ms>-<seq>.json` in the current
working directory. The timestamp + atomic counter suffix ensures
concurrent or repeated calls don't clobber each other.
- Failures while writing the dump are logged to stderr and otherwise
swallowed — a debug toggle must never fail a build.
The JSON document contains:
- `chunk_groups`: `string[][]` — module idents per chunk group, in the
order the algorithm sees them.
- `global_order`: `string[]` — the flat global order produced by
`linearize`.
- `global_order_chunks`: `string[][]` — the same modules grouped by the
merged segments produced by `split_into_chunks` (e.g. `[["a","b"],
["c"], ["d","e","f"]]`).
- `modules`: `[{ ident, size, style_type }]` — per-module metadata where
`size` is the chunk item size in bytes (the same value used by the cost
model) and `style_type` is `"GlobalStyle"` or `"IsolatedStyle"`.
Verification: `cargo clippy -p turbopack-core --no-deps` is clean and
the existing `style_groups_graph` test suite passes (53 tests).
No user-facing config change, no docs change — the env var is
intentionally undocumented and only meant for triage.
Closes NEXT-
Fixes #
---------
Co-authored-by: v-work-app[bot] <262237222+v-work-app[bot]@users.noreply.github.com>
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Tobias Koppers <sokra@users.noreply.github.com>
