Benjamin Woodruff

This commit performs a **refactoring** within the **Turbopack core reference handling** module to improve code clarity and accuracy. It **renames** the `asset` field to `module` within the `SingleModuleReference` struct, as the field specifically holds a `Module` type rather than a generic `Asset`. This **internal code quality improvement** ensures that the field's name accurately reflects its stored type, enhancing readability and maintainability. The change impacts the `resolve_reference` method and the `new` constructor of `SingleModuleReference`, where the field is used.

This commit **refactors Turbopack's core `Effect` system** to correctly implement the `TraceRawVcs` and `NonLocalValue` traits. This **preparatory change** is crucial for enabling `ResolvedVc` values, such as `FileSystemPath`, to be stored directly within `Effect`s, which is a prerequisite for a future tracing garbage collector. It updates the `Effect` and `DynEffect` traits in `turbo-tasks/src/effect.rs` to include these bounds, modifies internal `EffectState` and `apply` logic, and extends `TraceRawVcs` implementations to various types across `turbo-tasks` and `turbo-tasks-fs`. This **internal architectural improvement** lays the groundwork for more robust dependency tracking and memory management within Turbopack, without directly impacting user-facing functionality.

This commit **refactors** the **Turbopack `turbo-tasks` core** by redefining the internal `Effect` mechanism from a closure-based representation to a **trait-based system**. Specifically, the `Effect` type in `turbo-tasks/src/effect.rs` is now a trait, introducing `DynEffect` for dynamic dispatch and updating `emit_effect` and `EffectInstance`. This change also updates the **`turbo-tasks-fs` module** to utilize the new trait-based `Effect` for file and link writing operations, including `write` and `write_link`. This **internal architectural improvement** is crucial for enabling future implementation of `TraceRawVcs` on these deferred file write operations, enhancing the system's traceability.

This commit **optimizes the Turbopack development build process** by configuring the default `dev` profile to use `debug = "line-tables-only"` in `Cargo.toml`. This **build configuration adjustment** significantly **reduces the size of development build artifacts** for Rust components like `next-napi-bindings`, potentially improving build times and disk usage for developers who do not frequently use a debugger. To maintain full debugging capabilities when necessary, a new `dev-with-debug` profile has been introduced, allowing developers to explicitly opt-in to comprehensive debug information. This change primarily affects the **Turbopack build system's developer experience** and resource efficiency.

This commit **refactors** the **Turbopack build system** by **merging** the `release-with-assertions-no-lto` profile into `release-with-assertions`. The `Cargo.toml` configuration is updated to set `lto = false` within `release-with-assertions`, making the separate `no-lto` profile redundant. This **maintenance** change **simplifies build configurations**, **reduces `target` directory bloat**, and streamlines development by removing an unnecessary profile. As a result, the **`next-swc` package's unit test script** (`test-cargo-unit`) is updated to exclusively use the consolidated `release-with-assertions` profile.

This commit **removes** the `architecture.md` file from the **Turbopack documentation** within the `turbopack` crate. This is a **documentation cleanup** effort, as the content of the removed file was either outdated, misleading, or already better documented elsewhere in the project. By eliminating this obsolete document, the change improves the overall accuracy and relevance of the **Turbopack** project's documentation, guiding users to more current and correct information.

This commit **migrates and significantly enhances the documentation** for the **Turbopack chunking process** within the `turbopack-core` crate. It introduces a comprehensive `chunking.md` file, detailing concepts such as graph walk, module batching, and chunk item creation, which is now integrated as module-level documentation via `turbopack-core/src/lib.rs`. This **documentation improvement** involved extensive proof-reading and minor updates to ensure correctness against the codebase, clarifying names, distinguishing between traits and structs, and adding details like dev vs production chunking. Additionally, a minor **documentation fix** corrects a reference in `turbopack/crates/turbopack-core/src/chunk/mod.rs` from `Chunk` to `ChunkItem` for accuracy.

This commit significantly **improves documentation** for the **`turbopack-core`** crate by migrating conceptual content about "layers" (Sources, Modules, Output Assets) from an external `mdbook` to **Rustdoc**. It introduces a new `layers.md` file, embeds it into `src/lib.rs` as a dummy `_layers` module, and adds cross-references from the `Source`, `Module`, and `OutputAsset` traits. This **documentation enhancement** makes critical architectural concepts more accessible and integrated directly within the generated Rust API documentation, thereby improving the developer experience for those working with Turbopack's core components.

This commit performs extensive **documentation cleanup** and **CI pipeline enhancement** across the `turbopack` ecosystem. It resolves all warnings generated by `cargo doc --no-deps --workspace`, significantly improving the clarity and completeness of internal documentation for numerous structs, traits, functions, and constants within modules like `turbopack-core`, `turbo-tasks-fs`, and `turbopack-dev-server`. A new `rust-check-doc` script is also introduced and integrated into the `next-swc` CI configuration, ensuring that documentation quality is maintained going forward. This work also includes a minor **refactoring** by removing dead code, specifically `turbopack/crates/turbopack-dev-server/src/source/conditional.rs`.

This commit **removes the old `macos-compress` script** from the **Turbopack** build system, addressing several critical issues. This **maintenance** and **cleanup** task eliminates a problematic build optimization that could lead to **`target` directory corruption** on macOS due to non-atomic file operations and failure to acquire `cargo` locks. Furthermore, its removal prevents the script from inadvertently breaking `pnpm`'s APFS data deduplication for `node_modules`, ensuring more robust and reliable builds on macOS.

This commit performs a significant **refactoring** within the **Turbopack** `turbo-tasks` backend by **removing the `IntoTraitRef` trait**. The functionality previously provided by this trait is now implemented as an **inherent `into_trait_ref` method on the `Vc` struct**, simplifying the internal API. This change was made because the trait had only a single implementation, making it redundant. Consequently, numerous files across various `turbopack` crates, including `next-api`, `turbopack-browser`, and `turbopack-core`, have been updated to remove the no-longer-used `IntoTraitRef` import. This improves code clarity and reduces unnecessary abstraction in the core task system.

This commit **migrates documentation** for the **singleton pattern** within the **`turbopack/crates/turbo-tasks`** module. Previously hosted in an external `mdbook`, this essential guide is now integrated directly into the crate's **Rustdoc** via `singleton_pattern.md` and referenced in `README.md`. This change significantly improves the **discoverability and accessibility** of crucial `turbo-tasks` architectural patterns for developers. The work enhances the overall **developer experience** by centralizing documentation within the code's native tooling.

This commit **migrates documentation** for the **`turbo-tasks` trait system** from an external `mdbook` to integrated `rustdocs`. It significantly **enhances and clarifies the documentation** for key traits like `VcValueType`, `VcValueTrait`, `Upcast`, and `UpcastStrict`, along with macros such as `value_trait` and `value_impl`. This **documentation improvement** provides detailed explanations, usage examples, and covers concepts like upcasting, downcasting, and sidecasting. The work also includes minor **bug fixes** for outdated information, making the `turbo-tasks` API easier to understand and use for developers.

This commit **migrates and updates the documentation** for the **`TaskInput` trait** within the `turbopack/crates/turbo-tasks` module. Existing content from an external `mdbook` source has been integrated directly into the **Rustdoc** comments, significantly expanding details on serialization, hashing, `Vc<T>`, and deriving `TaskInput`. During this **documentation update**, outdated information (like references to `Value`) was removed, and crucial notes on **serialization of reference-counted types** and `TaskInput`'s implementation on `Arc` were added. This effort greatly **improves the discoverability and accuracy of developer documentation** for a core `turbo-tasks` concept.

This commit **refactors and updates the documentation** for the **`turbo_tasks` crate** within Turbopack. It migrates existing "tasks" documentation from an external mdbook to **inline Rustdoc** for the `#[turbo_tasks::function]` macro. This involves adding comprehensive explanations of argument/return type rewriting rules and method examples to `function.md`, which is then integrated into `src/lib.rs` as the macro's official documentation. Additionally, `README.md` is updated to refine the definition of 'Tasks' and remove outdated external links. This **documentation improvement** enhances the discoverability and accuracy of core `turbo_tasks` concepts for developers.

This commit significantly **enhances and centralizes the documentation** for the **`Vc` (Value Cell) system** within the **`turbopack/crates/turbo-tasks`** crate. It integrates previously external content into the Rustdocs, introducing a new comprehensive `README.md` for `Vc` and updating existing documentation for the `value` macro, `RawVc`, and `ResolvedVc`. This **documentation improvement** clarifies `Vc` behavior, serialization, and related concepts, making the core Turbopack mechanisms more accessible and understandable for developers.

This commit significantly **improves the documentation** for the **`turbo-tasks` crate** within Turbopack by **merging conceptual content** from an external `mdbook` page directly into the crate's top-level `rustdoc`. It introduces a new `turbopack/crates/turbo-tasks/README.md` file containing comprehensive details on Turbo Tasks concepts, primitives, and incremental builds, which is then included in `turbopack/crates/turbo-tasks/src/lib.rs`. This **documentation refactoring** provides a more unified and accessible resource for understanding the core principles of Turbo Tasks, enhancing developer experience by centralizing information and adding illustrative graphics.

This commit introduces a **fix** for a long-standing **developer experience issue** within the **Next.js build process** related to `pnpm` binary symlink creation. It resolves a "catch-22" where `pnpm install` would fail to set up necessary binary symlinks until after `pnpm build` completed, requiring developers to run `pnpm install` twice on fresh checkouts. A new `pnpm preinstall` script, `scripts/create-next-bin-placeholder.mjs`, now creates placeholder binaries for `next`, `create-next-app`, and `devlow-bench` if they don't exist, ensuring that `pnpm` can correctly establish symlinks. This **improves the initial setup workflow** by allowing `pnpm next` to provide a helpful error message before the full build, streamlining the **developer onboarding and build environment setup**.

This commit **adds comprehensive documentation** for **Turbopack tracing** to the project's contributing guide. It introduces a new `tracing.md` file under `contributing/turbopack`, detailing how to use environment variables, viewer tools, and various visualization options for tracing. The **new documentation**, adapted from existing Turbopack rust docs, includes important updates like the correct trace file path (`.next/trace-turbopack`) and mentions of `pnpm next internal trace`. This **documentation improvement** significantly enhances the developer experience for debugging and performance analysis within the **Turbopack** ecosystem.

This commit delivers a significant **documentation update** to the **contributing guidelines** within `contributing/core/developing.md`. It **updates and reorganizes the local development setup instructions**, addressing out-of-date information and enhancing clarity for contributors. Specifically, new sections have been added to cover **JavaScript and Rust dependencies**, alongside clarified commands for repository cloning, branching, and building. This **maintenance** effort improves the onboarding experience for new and existing developers by providing more accurate and helpful guidance for setting up their local development environment.