Improve -Zls diagnostic message on .rs files

compiler/rustc_driver_impl/src/lib.rs

@@ -597,6 +597,16 @@ fn process_rlink(sess: &Session, compiler: &interface::Compiler) {
 fn list_metadata(sess: &Session, metadata_loader: &dyn MetadataLoader) {
     match sess.io.input {
         Input::File(ref path) => {
+            if path.extension().is_some_and(|extension| extension == "rs") {
+                let mut err = sess
+                    .dcx()
+                    .struct_fatal("`-Zls` takes a `.rmeta` file as input, not a source file");
+                if rustc_session::utils::was_invoked_from_cargo() {
+                    // Give a Cargo-tailored suggestion if we're coming from Cargo
+                    err.note("use `rustc +nightly -Zls=... path/to/file.rmeta` directly, instead of going through Cargo");
+                }
+                err.emit();
+            }
             let mut v = Vec::new();
             locator::list_file_metadata(
                 &sess.target,

src/doc/unstable-book/src/compiler-flags/ls.md

@@ -0,0 +1,17 @@
+# `ls`
+
+---
+
+Option `-Zls` instructs the compiler to list all metadata from a given metadata file (i.e. files with the `.rmeta` extension).
+
+This allows for debugging the metadata emitted by an earlier compilation.
+
+Note that, while `rustc` usually works with `.rs` files, this option is meant purely for analyzing `.rmeta` files, and does not produce any compilation artifact.
+
+## Example
+
+```sh
+rustc +nightly -Zls=all target/debug/deps/libmy_crate-*.rmeta
+```
+
+This lists to stdout all metadata from the given `.rmeta` file