turbopack_ecmascript/references/esm/mangle/

mod.rs

//! Shortening ("mangling") of the export names a module exposes to other modules.
//!
//! A module's export keys usually only exist to link modules together: the producing module emits
//! `{ someVeryLongExportName: () => … }` and every consumer reads
//! `ns["someVeryLongExportName"]`. Both sides are generated by us, so the key can be replaced by a
//! much shorter one — as long as producer and consumer agree, and as long as the name is not
//! observable from user code.
//!
//! [`mangled_export_names`] is the single source of truth for that mapping. Both the producer
//! ([`super::export::EsmExports::code_generation`]) and the consumer
//! ([`super::base::ReferencedAsset`]) ask it for the *target* module's map, so they cannot
//! disagree. It returns an empty map whenever the module has to keep its original names — the
//! same effect as mangling every name to itself, so callers never need to branch on "did mangling
//! even apply here", only look a name up and fall back to itself.
//!
//! Code generation that spells an export access out **as a string** — rather than going through
//! `ReferencedAssetIdent`, which handles this automatically — must resolve its key through
//! [`generated_export_key`]. A hard-coded `["someExport"]` in generated source silently misses as
//! soon as the target module's exports are mangled.

mod table;

use anyhow::Result;
use turbo_frozenmap::FrozenMap;
use turbo_rcstr::RcStr;
use turbo_tasks::{ResolvedVc, Vc};
use turbopack_core::{
    chunk::ChunkingContext, module_graph::binding_usage_info::ModuleExportUsageInfo,
};

use self::table::shorten_to_unique_names;
use crate::chunk::{EcmascriptChunkPlaceable, EcmascriptExports};

/// A module's export name mapping: original export name -> the key actually used in the output.
///
/// `None` means the module is not eligible for mangling at all and keeps every original name (see
/// [`mangled_export_names`] for the conditions). `Some` covers only the exports that were actually
/// *renamed* — an export that kept its own name because it was already short enough, or because it
/// lost every hash collision, is not a key in the map. So a missing key always means "use the
/// original name", and callers that only want the correct output key can ignore the distinction
/// entirely (see [`generated_export_key`]); the `canMangle` reporting in
/// [`crate::references::exports_info`] is the one caller that needs to tell "not eligible" from
/// "eligible but unchanged", which is exactly what the `Option` gives it.
#[turbo_tasks::value(transparent)]
pub struct MangledExportNames(pub Option<FrozenMap<RcStr, RcStr>>);

/// Computes the mangled export names of `module`, or `None` when its exports must keep their
/// original names.
///
/// Both the producing and the consuming side call this for the same `module`, which is what
/// guarantees they agree. The mapping covers the module's *used* exports: unused exports are not
/// emitted at all, so giving them names would only make the remaining names longer.
///
/// A module keeps its original names when any of these hold:
///
/// 1. mangling is disabled for the module that owns these exports,
/// 2. its export usage is [`ModuleExportUsageInfo::All`] — a namespace import, a computed property
///    access, an unresolvable `export *`, or a module referenced from outside the module graph
///    (entries, which are seeded with `All`). This is what a plain `import * as ns` reaches in
///    practice, whether or not the namespace object escapes: the reads are not enumerated, so the
///    usage widens to `All`. Note that widening propagates, so splitting such a module into a
///    facade and a locals module does not rescue the locals module,
/// 3. it is read through a namespace value whose used names *are* known — in practice a dynamic
///    `import()` with an enumerated export list (`import(/* webpackExports: [...] */ "…")`). We
///    know which names are used, but not that every read of them was lowered to a direct named
///    access, so an original name may still be read by user code,
/// 4. its exports are not statically known ECMAScript exports, or contain dynamic re-exports.
///
/// None of these depend on the individual export, so "is `e` a candidate for mangling" is exactly
/// "is this `Some`, and is `e` used" — the per-name step (hashing into a short identifier) never
/// itself excludes a name.
#[turbo_tasks::function]
pub async fn mangled_export_names(
    module: ResolvedVc<Box<dyn EcmascriptChunkPlaceable>>,
    chunking_context: Vc<Box<dyn ChunkingContext>>,
) -> Result<Vc<MangledExportNames>> {
    // (4) Only statically known ESM exports can be renamed.
    let EcmascriptExports::EsmExports(exports) = *module.get_exports().await? else {
        return Ok(Vc::cell(None));
    };

    // (1) Disabled for the module these exports belong to. Deliberately independent of whether
    // this build minifies at all: mangling and minification are two separate concerns, and a
    // caller may want either without the other.
    if !exports.await?.mangle_export_names {
        return Ok(Vc::cell(None));
    }

    let usage = chunking_context
        .module_export_usage(*ResolvedVc::upcast(module))
        .await?;

    // (3) An original name may still be read through a namespace value.
    if usage.namespace_object_may_escape {
        return Ok(Vc::cell(None));
    }

    // (2) We don't know which exports are used, so we don't know that all uses are ours.
    let usage_info = usage.export_usage.await?;
    let ModuleExportUsageInfo::Exports(used) = &*usage_info else {
        return Ok(Vc::cell(None));
    };
    if used.is_empty() {
        return Ok(Vc::cell(None));
    }

    // (4) `export * from "./some-dynamic-cjs"` is resolved at runtime by property access on the
    // original names, and a used set that resolves to no actual export at all leaves nothing to
    // mangle.
    let expanded = exports.expand_exports(*usage.export_usage).await?;
    if !expanded.dynamic_exports.is_empty() || expanded.exports.is_empty() {
        return Ok(Vc::cell(None));
    }

    // Every emitted export is mangled, `default` and `__esModule` included.
    //
    // Neither is a runtime contract *as an export name*. The runtime paths that look `'default'` up
    // by name — the CommonJS interop in `esmNamespaceObject` and the proxy traps behind
    // `ensureDynamicExports` — only apply to CommonJS targets and to modules with dynamic
    // re-exports, and both already keep their original names via the checks above. `__esModule` is
    // how a CommonJS module signals interop *to* ESM, so an ESM module that happens to export that
    // name is just an ordinary export. `__esModule` still cannot be *assigned* to some other
    // export, because the runtime defines that property itself; see `RESERVED_KEYS` in `table`.
    Ok(Vc::cell(Some(shorten_to_unique_names(
        expanded.exports.keys(),
    ))))
}

/// The key that generated code has to use to read `export` from `module` — the mangled key when
/// the module's exports are mangled, and `export` itself otherwise.
///
/// **Every** piece of code generation that materializes an export access as a string has to get its
/// key from here, or the access will miss when the module is mangled. That includes generated
/// source text (`__turbopack_require__(id)["default"](…)` and friends) as well as AST built by
/// hand. Code that goes through `ReferencedAssetIdent` (see `super::base`) is already covered.
///
/// `module` must be the module that actually *produces* the export. For a re-export, resolve to the
/// producing module first (as `ReferencedAsset::get_ident_inner` does), because each module mangles
/// its own keys independently.
pub async fn generated_export_key(
    module: ResolvedVc<Box<dyn EcmascriptChunkPlaceable>>,
    chunking_context: Vc<Box<dyn ChunkingContext>>,
    export: &RcStr,
) -> Result<RcStr> {
    let names = mangled_export_names(*module, chunking_context).await?;
    Ok(names
        .as_ref()
        .and_then(|names| names.get(export))
        .cloned()
        .unwrap_or_else(|| export.clone()))
}