fix(trim-paths): unambiguous and reversible remap rules (#17302)

### What does this PR try to resolve?

Part of <#12137>.
This was discussed during 2026 all-hands

rust-lang/all-hands-2026#38 (comment)

Every remap rule now substitutes a distinct prefix
instead of stripping the source prefix to an empty string.
This makes the source remap more unambiguous and reversible.

| Category | From | To |

|---------------------|----------------------------------------------|------------------------------------|
| Sysroot | `<sysroot>/lib/rustlib/src/rust` | `/rustc/<commit-hash>` |
| Registry dep | `~/cargo/registry/src/<registry-dir>` |
`/cargo/registry/<registry-id>` |
| Git dep | `~/cargo/git/checkouts/<repo-dir>/<rev-dir>` |
`/cargo/git/<git-source-id>/<rev>` |
| Workspace | `<workspace-root>` | `.` (workspace-relative) |
| Path dep outside ws | `<pkg-root>` | `/cargo/path/<name>-<version>` |
| Vendored | `<pkg-root>` (by file location) | workspace or path rules
above |
| Build directory | `<build-dir>` | `/cargo/build-dir` |

### How to test and review this PR?

Commit by commit.

* Old tests show the remap behavior changes.
* New tests verify vendored dependencies are covered.
* Docs are updated.

Author: epage

doc/book/src/reference/unstable.md

@@ -1549,11 +1549,32 @@ But the paths to these separate files are sanitized.
 
 If `trim-paths` is not `none` or `false`, then the following paths are sanitized if they appear in a selected scope:
 
-1. Path to the source files of the standard and core library (sysroot) will begin with `/rustc/[rustc commit hash]`,
+1. Path to the source files of the standard and core library (sysroot) will begin with `/rustc/<rustc commit hash>`,
    e.g. `/home/username/.rustup/toolchains/nightly-x86_64-unknown-linux-gnu/lib/rustlib/src/rust/library/core/src/result.rs` ->
    `/rustc/fe72845f7bb6a77b9e671e6a4f32fe714962cec4/library/core/src/result.rs`
-2. Path to the current package will be stripped, relatively to the current workspace root, e.g. `/home/username/crate/src/lib.rs` -> `src/lib.rs`.
-3. Path to dependency packages will be replaced with `[package name]-[version]`. E.g. `/home/username/deps/foo/src/lib.rs` -> `foo-0.1.0/src/lib.rs`
+2. Path to the current package will be stripped,
+   relatively to the current workspace root,
+   e.g. `/home/username/crate/src/lib.rs` -> `src/lib.rs`.
+   This also covers path dependencies located inside the workspace directory.
+3. Path to a registry dependency will begin with `/cargo/registry/<registry id>`,
+   which replaces the registry's extraction directory,
+   e.g. `/home/username/.cargo/registry/src/index.crates.io-6f17d22d3f0a95d1/foo-0.1.0/src/lib.rs` ->
+   `/cargo/registry/6f17d22d3f0a95d1/foo-0.1.0/src/lib.rs`.
+4. Path to a git dependency will begin with `/cargo/git/<git source id>/<revision>`,
+   which replaces the checkout directory.
+   `<revision>` is a prefix of the resolved commit ID recorded in the lockfile.
+5. Path to a path dependency outside the workspace will be replaced with
+   `/cargo/path/<package name>-<package version>`.
+6. Path into the build directory, for example `OUT_DIR` generated sources,
+   will begin with `/cargo/build-dir`.
+
+`<registry id>` and `<git source id>` are opaque stable hashes of the dependency's source.
+
+Vendored copies of registry or git dependencies
+(via [source replacement](./source-replacement.md))
+are sanitized by their file location instead,
+like workspace paths when inside the workspace directory,
+otherwise like path dependencies.
 
 When a path to the source files of the standard and core library is *not* in scope for sanitization,
 the emitted path will depend on if `rust-src` component is present.

src/compiler/custom_build.rs

@@ -403,7 +403,7 @@ fn build_work(build_runner: &mut BuildRunner<'_, '_>, unit: &Unit) -> CargoResul
     if let Some(trim_paths) = unit.profile.trim_paths.as_ref() {
         cmd.env("CARGO_TRIM_PATHS_SCOPE", trim_paths.to_string());
         if !trim_paths.is_none() {
-            let pairs = super::trim_paths_remap(build_runner, unit);
+            let pairs = super::trim_paths::trim_paths_remap(build_runner, unit);
             cmd.env(
                 "CARGO_TRIM_PATHS_REMAP",
                 paths::join_paths(&pairs, "CARGO_TRIM_PATHS_REMAP")?,

src/compiler/mod.rs

@@ -48,6 +48,7 @@ mod output_sbom;
 pub mod rustdoc;
 pub mod standard_lib;
 pub mod timings;
+mod trim_paths;
 mod unit;
 pub mod unit_dependencies;
 pub mod unit_graph;
@@ -95,6 +96,8 @@ pub(crate) use self::layout::Layout;
 pub use self::lto::Lto;
 use self::output_depinfo::output_depinfo;
 use self::output_sbom::build_sbom;
+use self::trim_paths::trim_paths_args;
+use self::trim_paths::trim_paths_args_rustdoc;
 use self::unit_graph::UnitDep;
 
 use crate::compiler::future_incompat::FutureIncompatReport;
@@ -115,8 +118,6 @@ use crate::workspace::{Feature, PackageId, Target};
 
 use cargo_util::{ProcessBuilder, ProcessError, paths};
 use cargo_util_schemas::manifest::TomlDebugInfo;
-use cargo_util_schemas::manifest::TomlTrimPaths;
-use cargo_util_schemas::manifest::TomlTrimPathsValue;
 use cargo_util_terminal::Verbosity;
 use rustfix::diagnostics::Applicability;
 
@@ -1525,159 +1526,6 @@ fn features_args(unit: &Unit) -> Vec<OsString> {
     args
 }
 
-/// Like [`trim_paths_args`] but for rustdoc invocations.
-fn trim_paths_args_rustdoc(
-    cmd: &mut ProcessBuilder,
-    build_runner: &BuildRunner<'_, '_>,
-    unit: &Unit,
-    trim_paths: &TomlTrimPaths,
-) -> CargoResult<()> {
-    match trim_paths {
-        // rustdoc supports diagnostics trimming only.
-        TomlTrimPaths::Values(values) if !values.contains(&TomlTrimPathsValue::Diagnostics) => {
-            return Ok(());
-        }
-        _ => {}
-    }
-
-    for pair in trim_paths_remap(build_runner, unit) {
-        let mut arg = OsString::from("--remap-path-prefix=");
-        arg.push(pair);
-        cmd.arg(arg);
-    }
-
-    Ok(())
-}
-
-/// Generates the `--remap-path-scope` and `--remap-path-prefix` for [RFC 3127].
-/// See also unstable feature [`-Ztrim-paths`].
-///
-/// [RFC 3127]: https://rust-lang.github.io/rfcs/3127-trim-paths.html
-/// [`-Ztrim-paths`]: https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#profile-trim-paths-option
-fn trim_paths_args(
-    cmd: &mut ProcessBuilder,
-    build_runner: &BuildRunner<'_, '_>,
-    unit: &Unit,
-    trim_paths: &TomlTrimPaths,
-) -> CargoResult<()> {
-    if trim_paths.is_none() {
-        return Ok(());
-    }
-
-    // feature gate was checked during manifest/config parsing.
-    cmd.arg(format!("--remap-path-scope={trim_paths}"));
-
-    for pair in trim_paths_remap(build_runner, unit) {
-        let mut arg = OsString::from("--remap-path-prefix=");
-        arg.push(pair);
-        cmd.arg(arg);
-    }
-
-    Ok(())
-}
-
-/// Computes the `<from>=<to>` path remap pairs for [RFC 3127] trim-paths.
-///
-/// Order of `--remap-path-prefix` flags is important for `-Zbuild-std`.
-/// We want to show `/rustc/<hash>/library/std` instead of `std-0.0.0`.
-///
-/// [RFC 3127]: https://rust-lang.github.io/rfcs/3127-trim-paths.html
-pub(crate) fn trim_paths_remap(build_runner: &BuildRunner<'_, '_>, unit: &Unit) -> [OsString; 3] {
-    [
-        package_remap(build_runner, unit),
-        build_dir_remap(build_runner),
-        sysroot_remap(build_runner, unit),
-    ]
-}
-
-/// Path prefix remap rules for sysroot.
-///
-/// This remap logic aligns with rustc:
-/// <https://github.com/rust-lang/rust/blob/c2ef3516/src/bootstrap/src/lib.rs#L1113-L1116>
-fn sysroot_remap(build_runner: &BuildRunner<'_, '_>, unit: &Unit) -> OsString {
-    let mut remap = OsString::new();
-    remap.push({
-        // See also `detect_sysroot_src_path()`.
-        let mut sysroot = build_runner.bcx.target_data.info(unit.kind).sysroot.clone();
-        sysroot.push("lib");
-        sysroot.push("rustlib");
-        sysroot.push("src");
-        sysroot.push("rust");
-        sysroot
-    });
-    remap.push("=");
-    remap.push("/rustc/");
-    if let Some(commit_hash) = build_runner.bcx.rustc().commit_hash.as_ref() {
-        remap.push(commit_hash);
-    } else {
-        remap.push(build_runner.bcx.rustc().version.to_string());
-    }
-    remap
-}
-
-/// Path prefix remap rules for dependencies.
-///
-/// * Git dependencies: remove `~/.cargo/git/checkouts` prefix.
-/// * Registry dependencies: remove `~/.cargo/registry/src` prefix.
-/// * Others (e.g. path dependencies):
-///     * relative paths to workspace root if inside the workspace directory.
-///     * otherwise remapped to `<pkg>-<version>`.
-fn package_remap(build_runner: &BuildRunner<'_, '_>, unit: &Unit) -> OsString {
-    let pkg_root = unit.pkg.root();
-    let ws_root = build_runner.bcx.ws.root();
-    let mut remap = OsString::new();
-    let source_id = unit.pkg.package_id().source_id();
-    if source_id.is_git() {
-        remap.push(
-            build_runner
-                .bcx
-                .gctx
-                .git_checkouts_path()
-                .as_path_unlocked(),
-        );
-        remap.push("=");
-    } else if source_id.is_registry() {
-        remap.push(
-            build_runner
-                .bcx
-                .gctx
-                .registry_source_path()
-                .as_path_unlocked(),
-        );
-        remap.push("=");
-    } else if pkg_root.strip_prefix(ws_root).is_ok() {
-        remap.push(ws_root);
-        remap.push("=."); // remap to relative rustc work dir explicitly
-    } else {
-        remap.push(pkg_root);
-        remap.push("=");
-        remap.push(unit.pkg.name());
-        remap.push("-");
-        remap.push(unit.pkg.version().to_string());
-    }
-    remap
-}
-
-/// Remap all paths pointing to `build.build-dir`,
-/// i.e., `[BUILD_DIR]/debug/deps/foo-[HASH].dwo` would be remapped to
-/// `/cargo/build-dir/debug/deps/foo-[HASH].dwo`
-/// (note the `/cargo/build-dir` prefix).
-///
-/// This covers scenarios like:
-///
-/// * Build script generated code. For example, a build script may call `file!`
-///   macros, and the associated crate uses [`include!`] to include the expanded
-///   [`file!`] macro in-place via the `OUT_DIR` environment.
-/// * On Linux, `DW_AT_GNU_dwo_name` that contains paths to split debuginfo
-///   files (dwp and dwo).
-fn build_dir_remap(build_runner: &BuildRunner<'_, '_>) -> OsString {
-    let build_dir = build_runner.bcx.ws.build_dir();
-    let mut remap = OsString::new();
-    remap.push(build_dir.as_path_unlocked());
-    remap.push("=/cargo/build-dir");
-    remap
-}
-
 /// Generates the `--check-cfg` arguments for the `unit`.
 fn check_cfg_args(unit: &Unit) -> Vec<OsString> {
     // The routine below generates the --check-cfg arguments. Our goals here are to