Struct Linker 

pub struct Linker { /* private fields */ }

Links packages from the global store into a project’s node_modules/.

Uses pnpm-compatible symlink layout backed by a global virtual store:

• Packages are materialized once in ~/.cache/aube/virtual-store/ (or $XDG_CACHE_HOME/aube/virtual-store/)
• Per-project .aube/ entries are symlinks into the global virtual store
• Top-level node_modules/<name> entries are symlinks to .aube/<dep_path>/node_modules/<name> (matching pnpm)
• Transitive deps live as sibling symlinks inside .aube/<dep_path>/node_modules/ so Node’s directory walk finds them when resolving from inside the package

Implementations

impl Linker

pub fn new(store: &Store, strategy: LinkStrategy) -> Self

pub fn with_node_linker(self, node_linker: NodeLinker) -> Self

Select the layout mode. Defaults to NodeLinker::Isolated (pnpm’s .aube/-backed virtual-store layout); Hoisted dispatches link_all / link_workspace to the flat node_modules materializer in crate::hoisted.

pub fn node_linker(&self) -> NodeLinker

Current layout mode. The install driver reads this after linking to decide how to resolve per-package directories for bin linking and lifecycle scripts — isolated uses the .aube/<dep_path> convention, hoisted consults the HoistedPlacements returned on LinkStats.

pub fn with_modules_dir_name(self, name: impl Into<String>) -> Self

Override the name of the project-level node_modules directory (pnpm’s modules-dir setting). Empty strings are coerced back to the default so a .npmrc typo can’t make the linker write into the project root itself. The setting only affects the outer directory name — the inner virtual-store layout still uses the literal node_modules that Node’s resolver expects when walking up from inside a package.

pub fn modules_dir_name(&self) -> &str

Project-level modules directory name. aube reads this when it needs the same path the linker writes into — keeping the computation DRY with whatever the linker was built with.

pub fn with_aube_dir_override(self, path: PathBuf) -> Self

Override the per-project virtual-store path (pnpm’s virtualStoreDir). The supplied path should be absolute — aube resolves relative .npmrc / pnpm-workspace.yaml values against the project dir before handing them here. When not set, the linker derives the virtual store path as <project_dir>/<modules_dir_name>/.aube at link time, which matches the historical behavior.

pub fn aube_dir_for(&self, project_dir: &Path) -> PathBuf

Compute the effective virtual-store path for project_dir. Consults the override installed by with_aube_dir_override if any; otherwise falls back to <project_dir>/<modules_dir>/.<name>. Used internally by link_all; also called by the install driver’s “already linked” fast path so both sites land on the same directory when the user has overridden virtualStoreDir.

pub fn with_link_concurrency(self, concurrency: Option<usize>) -> Self

Override the package-level linker worker count. Values below 1 are ignored by the install driver before they reach this point.

pub fn with_use_global_virtual_store(self, enabled: bool) -> Self

Override the global-virtual-store toggle set by Linker::new (which looks at CI). Callers use this to force per-project materialization when they’ve detected a consumer that breaks on directory symlinks escaping the project root — e.g. Next.js / Turbopack, which canonicalizes node_modules/<pkg> and rejects anything that lands outside its declared filesystem root.

pub fn with_project_local_dep_paths( self, dep_paths: impl IntoIterator<Item = String>, ) -> Self

Materialize selected dep paths into the project-local virtual store while all other packages continue to use the GVS.

Callers use this for package-specific compatibility transforms that must never mutate a shared store entry.

pub fn with_shamefully_hoist(self, shamefully_hoist: bool) -> Self

Enable pnpm’s shamefully-hoist mode. When true, every package in the graph gets a top-level node_modules/<name> symlink in addition to the direct-dep entries, producing npm’s flat layout at the cost of phantom-dep correctness. First-write-wins on duplicate names, so root deps always take precedence.

pub fn with_public_hoist_pattern(self, patterns: &[String]) -> Self

Configure pnpm’s public-hoist-pattern. Each input is a glob matched against package names; a leading ! flips it into a negation. After the usual direct-dep symlinks, every non-local package whose name matches at least one positive pattern and no negation gets a top-level node_modules/<name> symlink. Invalid patterns are silently dropped (same tolerance as pnpm), so a typo in .npmrc degrades to “not hoisted” instead of failing the install.

pub fn with_hoist(self, hoist: bool) -> Self

Toggle pnpm’s hoist setting. When true (the default), the hidden modules tree at node_modules/.aube/node_modules/ is populated via with_hoist_pattern. When false, that tree is skipped and any existing directory is swept so stale symlinks from a previous hoist=true run don’t keep resolving.

pub fn with_hoist_pattern(self, patterns: &[String]) -> Self

Configure pnpm’s hoist-pattern. Each input is a glob matched against package names; a leading ! flips it into a negation. Every non-local package in the graph whose name matches at least one positive pattern (and no negation) gets a node_modules/.aube/node_modules/<name> symlink — the hidden fallback dir for Node’s parent-directory walk. Invalid patterns are silently dropped (pnpm parity). Supplying an empty list or only-negation list means “hoist nothing”; leaving this unconfigured keeps the default * match.

pub fn with_hoist_workspace_packages(self, on: bool) -> Self

Toggle pnpm’s hoist-workspace-packages. When false, the linker skips creating node_modules/<ws-pkg> symlinks for workspace packages in every importer, including the root. Cross-importer workspace: deps already resolve through the lockfile, so only direct require('<ws-pkg>') from a package that doesn’t declare it stops working. Default true (pnpm parity).

pub fn with_hoisting_limits(self, limits: HoistingLimits) -> Self

Configure pnpm’s hoistingLimits for node-linker=hoisted. No-op for the default isolated linker.

pub fn with_dedupe_direct_deps(self, on: bool) -> Self

Toggle pnpm’s dedupe-direct-deps. When true, the linker skips creating a per-importer node_modules/<name> symlink for any direct dep whose root importer already declares the same package at the same resolved version — Node’s parent-directory walk from inside the workspace package still resolves the same copy via the root-level symlink, so consumer code is unaffected. Default false (pnpm parity). No-op under virtualStoreOnly=true (no per-importer symlink pass runs) and under NodeLinker::Hoisted (its workspace-wide placement plan deduplicates compatible packages independently).

pub fn with_virtual_store_dir_max_length(self, max_length: usize) -> Self

Override the virtual-store directory name length cap. Primarily a hook for tests and for parity with pnpm’s virtual-store-dir-max-length config; most callers should leave it at the default.

pub fn with_virtual_store_only(self, only: bool) -> Self

Toggle pnpm’s virtual-store-only. When enabled, link_all / link_workspace still populate .aube/<dep_path>/node_modules (and the shared global virtual store under ~/.cache/aube/virtual-store/) but skip the pass that writes top-level node_modules/<name> symlinks and the hoisting passes that target the same directory. No-op under NodeLinker::Hoisted — that layout is inherently a flat top-level materialization.

pub fn virtual_store_only(&self) -> bool

Whether this linker will skip the top-level node_modules/<name> symlink pass. Exposed so the install driver can omit root-level bin linking and lifecycle-script invocations when the user has asked for a virtual-store-only install — both operate on the top-level tree that won’t exist.

pub fn with_graph_hashes(self, hashes: GraphHashes) -> Self

Install a set of pre-computed graph hashes. Every virtual-store path the linker constructs after this point will use the hashed subdir name for the matching dep_path. Callers normally derive the hashes once per install via aube_lockfile::graph_hash::compute_graph_hashes and pass the result in here.

pub fn uses_global_virtual_store(&self) -> bool

Whether this linker populates the project’s .aube/ entries as symlinks into the shared virtual store (true) or materializes a per-project copy (false). Callers that want to mutate package directories after linking — e.g. running allowBuilds lifecycle scripts — need to know because shared-store writes leak across projects.

pub fn with_patches(self, patches: Patches) -> Self

Install a set of patch contents to apply at materialize time. Replaces any previously installed patches. Pair with with_graph_hashes whose patch_hash callback returns the same per-(name, version) digest, so the patched bytes land at a distinct virtual-store path from the unpatched ones.

impl Linker

pub fn link_all( &self, project_dir: &Path, graph: &LockfileGraph, package_indices: &BTreeMap<String, PackageIndex>, ) -> Result<LinkStats, Error>

Link all packages into node_modules for the given project.

pub fn link_workspace( &self, root_dir: &Path, graph: &LockfileGraph, package_indices: &BTreeMap<String, PackageIndex>, workspace_dirs: &BTreeMap<String, PathBuf>, ) -> Result<LinkStats, Error>

Link all packages for a workspace (multiple importers).

Creates the shared .aube/ virtual store at root, then for each workspace package creates node_modules/ with its direct deps linked from the root .aube/. Workspace packages that depend on each other get symlinks to the package directory.

impl Linker

pub fn detect_strategy(path: &Path) -> LinkStrategy

Detect the best linking strategy for the filesystem at the given path.

One-arg form. Probes within one dir. Fine when store and project node_modules share the same mount. Use the two-arg form for installs where the store lives on a different filesystem than the project (USB drives, bind mounts, Docker volumes, cross-drive Windows installs). Otherwise the probe reports hardlink based on project-FS self-test, then every real link call crosses an FS boundary and hits EXDEV. Runtime falls back to fs::copy per file silently, thousands of wasted syscalls, user thinks they got hardlinks.

Returns the same-filesystem strategy auto resolves to when the probe succeeds, Copy otherwise. The same-FS strategy is OS-specific: on macOS auto resolves to ReflinkAuto (APFS clonefile benchmarks ~1.91x faster than hardlink), on Linux and other targets it resolves to Hardlink (btrfs/xfs hardlink benchmarks ~2.4-2.6x faster than FICLONE reflink).

The macOS auto resolution is conservative on non-APFS volumes: clonefile is APFS-only, so on an HFS+ volume (external drives, Fusion/older disks) the same-FS hardlink probe succeeds and resolves ReflinkAuto, but the real clonefile then fails. link_file_fresh handles this by falling the reflink back to a hardlink (which HFS+ supports) before copy, so a non-APFS same-FS target still gets zero-cost links rather than a per-file copy. This probe never yields the plain Reflink strategy — that is reachable only through explicit packageImportMethod = clone / clone-or-copy, which keep a plain copy fallback.

pub fn detect_strategy_cross(src_dir: &Path, dst_dir: &Path) -> LinkStrategy

Two-arg probe. src is the store shard (or any dir on the store FS), dst is the project modules dir (or any dir on the destination FS). Probe creates a real cross-mount src file and tries to hardlink into dst, which catches EXDEV up front. A successful hardlink proves src and dst share a mount, so it doubles as the same-FS probe for reflink too (APFS clonefile / btrfs FICLONE require the same FS). Returns the OS-specific same-FS strategy when the probe succeeds (ReflinkAuto on macOS, Hardlink elsewhere), Copy otherwise.

pub fn ensure_in_virtual_store( &self, dep_path: &str, pkg: &LockedPackage, index: &PackageIndex, stats: &mut LinkStats, nested_link_targets: Option<&BTreeMap<String, PathBuf>>, ) -> Result<(), Error>

Materialize a package in the global virtual store if not already present.

Materialize dep_path into the shared global virtual store.

Uses atomic rename to avoid TOCTOU races: materializes into a PID-stamped temp directory, then renames into place. If another process wins the race, its result is kept and the temp dir is cleaned up.

Exposed so the install driver can pipeline GVS population into the fetch phase: as each tarball finishes importing into the CAS, the driver calls this to reflink the package into its ~/.cache/aube/virtual-store/<subdir> entry. Link step 1 then hits the pkg_nm_dir.exists() fast path and only creates the per-project .aube/<dep_path> symlink.

pub fn ensure_in_aube_dir( &self, aube_dir: &Path, dep_path: &str, pkg: &LockedPackage, index: &PackageIndex, stats: &mut LinkStats, nested_link_targets: Option<&BTreeMap<String, PathBuf>>, ) -> Result<(), Error>

Materialize a single package directly into the per-project virtual store at aube_dir/<dep_path>/node_modules/<name>/.

Idempotent: if the entry already exists, counts as cached and returns. Otherwise materializes into a unique temp directory and atomically renames that entry into place so duplicate in-process fetch events for the same dep-path cannot race while writing node_modules/.aube/<dep_path>/. Used by the install-time materializer to pipeline the link work into the fetch phase under non-GVS mode, so the dedicated link phase only has to create top-level node_modules/<name> symlinks.