rustdoc-json: add rlib path to ExternalCrate to enable robust crate resolution

Historically, it's not been possible to robustly resolve a cross-crate
item in rustdoc-json. If you had a `Id` that wasn't in `Crate::index`
(because it was defined in a different crate), you could only look it up
it `Crate::paths`. But there, you don't get the full information, only
an `ItemSummary`. This tells you the `path` and the `crate_id`.

But knowing the `crate_id` isn't enough to be able to build/find the
rustdoc-json output with this item. It's only use is to get a
`ExternalCrate` (via `Crate::external_crates`). But that only tells you
the `name` (as a string). This isn't enough to uniquely identify a
crate, as there could be multiple versions/features [1] [2].

This was originally proposed to be solved via LukeMathWalker's
`--orchestrator-id` proposal
(https://www.github.com/rust-lang/compiler-team/issues/635). But that
requires invasive changes to cargo/rustc. This PR instead implements
Urgau's proposal to re-use the path to a crate's rmeta/rlib as a unique
identifer. Callers can use that to determine which package it
corresponds to in the language of the build-system above rustc. E.g. for
cargo, `cargo rustdoc --message-format=json --output-format=json
-Zunstable-options`).

(Once you've found the right external crate's rustdoc-json output, you
still need to resolve the path->id in that crate. But that's """just"""
a matter of walking the module tree. We should probably still make that
nicer (by, for example, allowing sharing `Id`s between rustdoc-json
document), but that's a future concern)

For some notes from RustWeek 2025, where this was designed, see
https://hackmd.io/0jkdguobTnW7nXoGKAxfEQ

[1]: https://www.github.com/rust-lang/compiler-team/issues/635#issue-1714254865 § Problem
[2]: https://rust-lang.zulipchat.com/#narrow/channel/266220-t-rustdoc/topic/Identifying.20external.20crates.20in.20Rustdoc.20JSON/with/352701211

Author: aDotInTheVoid

src/librustdoc/json/mod.rs

@@ -302,6 +302,13 @@ impl<'tcx> FormatRenderer<'tcx> for JsonRenderer<'tcx> {
                                 ExternalLocation::Remote(s) => Some(s.clone()),
                                 _ => None,
                             },
+                            path: self
+                                .tcx
+                                .used_crate_source(*crate_num)
+                                .paths()
+                                .next()
+                                .expect("crate should have at least 1 path")
+                                .clone(),
                         },
                     )
                 })
@@ -339,20 +346,21 @@ mod size_asserts {
     // tidy-alphabetical-start
     static_assert_size!(AssocItemConstraint, 112);
     static_assert_size!(Crate, 184);
-    static_assert_size!(ExternalCrate, 48);
     static_assert_size!(FunctionPointer, 168);
     static_assert_size!(GenericArg, 80);
     static_assert_size!(GenericArgs, 104);
     static_assert_size!(GenericBound, 72);
     static_assert_size!(GenericParamDef, 136);
     static_assert_size!(Impl, 304);
-    // `Item` contains a `PathBuf`, which is different sizes on different OSes.
-    static_assert_size!(Item, 528 + size_of::<std::path::PathBuf>());
     static_assert_size!(ItemSummary, 32);
     static_assert_size!(PolyTrait, 64);
     static_assert_size!(PreciseCapturingArg, 32);
     static_assert_size!(TargetFeature, 80);
     static_assert_size!(Type, 80);
     static_assert_size!(WherePredicate, 160);
     // tidy-alphabetical-end
+
+    // These contains a `PathBuf`, which is different sizes on different OSes.
+    static_assert_size!(Item, 528 + size_of::<std::path::PathBuf>());
+    static_assert_size!(ExternalCrate, 48 + size_of::<std::path::PathBuf>());
 }

src/rustdoc-json-types/lib.rs

@@ -37,8 +37,8 @@ pub type FxHashMap<K, V> = HashMap<K, V>; // re-export for use in src/librustdoc
 // will instead cause conflicts. See #94591 for more. (This paragraph and the "Latest feature" line
 // are deliberately not in a doc comment, because they need not be in public docs.)
 //
-// Latest feature: Add `ItemKind::Attribute`.
-pub const FORMAT_VERSION: u32 = 56;
+// Latest feature: Add `ExternCrate::path`.
+pub const FORMAT_VERSION: u32 = 57;
 
 /// The root of the emitted JSON blob.
 ///
@@ -135,6 +135,12 @@ pub struct ExternalCrate {
     pub name: String,
     /// The root URL at which the crate's documentation lives.
     pub html_root_url: Option<String>,
+
+    /// A path from where this crate was loaded.
+    ///
+    /// This will typically be a `.rlib` or `.rmeta`. It can be used to determine which crate
+    /// this was in terms of whatever build-system invoked rustc.
+    pub path: PathBuf,
 }
 
 /// Information about an external (not defined in the local crate) [`Item`].

tests/run-make/rustdoc-json-external-crate-path/dep.rs

@@ -0,0 +1,4 @@
+/// dep.rs
+pub struct S;
+
+pub use trans_dep::S as TransDep;

tests/run-make/rustdoc-json-external-crate-path/entry.rs

@@ -0,0 +1,2 @@
+pub type FromDep = dep::S;
+pub type FromTransDep = dep::TransDep;

tests/run-make/rustdoc-json-external-crate-path/rmake.rs

@@ -0,0 +1,81 @@
+use std::path::PathBuf;
+
+use run_make_support::rustdoc_json_types::{Crate, ItemEnum, Path, Type, TypeAlias};
+use run_make_support::{cwd, rfs, rust_lib_name, rustc, rustdoc, serde_json};
+
+fn main() {
+    rustc().input("trans_dep.rs").edition("2024").crate_type("lib").run();
+
+    rustc()
+        .input("dep.rs")
+        .edition("2024")
+        .crate_type("lib")
+        .extern_("trans_dep", rust_lib_name("trans_dep"))
+        .run();
+
+    rustdoc()
+        .input("entry.rs")
+        .edition("2024")
+        .output_format("json")
+        .library_search_path(cwd())
+        .extern_("dep", rust_lib_name("dep"))
+        .arg("-Zunstable-options")
+        .run();
+
+    let bytes = rfs::read("doc/entry.json");
+
+    let krate: Crate = serde_json::from_slice(&bytes).expect("output should be valid json");
+
+    let root_item = &krate.index[&krate.root];
+    let ItemEnum::Module(root_mod) = &root_item.inner else { panic!("expected ItemEnum::Module") };
+
+    assert_eq!(root_mod.items.len(), 2);
+
+    let items = root_mod.items.iter().map(|id| &krate.index[id]).collect::<Vec<_>>();
+
+    let from_dep = items
+        .iter()
+        .filter(|item| item.name.as_deref() == Some("FromDep"))
+        .next()
+        .expect("there should be en item called FromDep");
+
+    let from_trans_dep = items
+        .iter()
+        .filter(|item| item.name.as_deref() == Some("FromTransDep"))
+        .next()
+        .expect("there should be en item called FromDep");
+
+    let ItemEnum::TypeAlias(TypeAlias {
+        type_: Type::ResolvedPath(Path { id: from_dep_id, .. }),
+        ..
+    }) = &from_dep.inner
+    else {
+        panic!("Expected FromDep to be a TypeAlias");
+    };
+
+    let ItemEnum::TypeAlias(TypeAlias {
+        type_: Type::ResolvedPath(Path { id: from_trans_dep_id, .. }),
+        ..
+    }) = &from_trans_dep.inner
+    else {
+        panic!("Expected FromDep to be a TypeAlias");
+    };
+
+    assert_eq!(krate.index.get(from_dep_id), None);
+    assert_eq!(krate.index.get(from_trans_dep_id), None);
+
+    let from_dep_externalinfo = &krate.paths[from_dep_id];
+    let from_trans_dep_externalinfo = &krate.paths[from_trans_dep_id];
+
+    let dep_crate_id = from_dep_externalinfo.crate_id;
+    let trans_dep_crate_id = from_trans_dep_externalinfo.crate_id;
+
+    let dep = &krate.external_crates[&dep_crate_id];
+    let trans_dep = &krate.external_crates[&trans_dep_crate_id];
+
+    assert_eq!(dep.name, "dep");
+    assert_eq!(trans_dep.name, "trans_dep");
+
+    assert_eq!(dep.path, cwd().join(rust_lib_name("dep")));
+    assert_eq!(trans_dep.path, cwd().join(rust_lib_name("trans_dep")));
+}

tests/run-make/rustdoc-json-external-crate-path/trans_dep.rs

@@ -0,0 +1,2 @@
+/// trans_dep.rs
+pub struct S;