Provide a more helpful diagnostic for shebangs inside of doctests

[epage]

Code

/// 
/// #!/usr/bin/env cargo
///
/// println!("hello");
/// 
pub struct Foo;

Current output

---- $DIR/failed-doctest-shebang.rs - Foo (line 6) stdout ----
error: macro expansion ignores `{` and any tokens following
  --> $SRC_DIR/std/src/macros.rs:LL:COL
   |
  ::: $DIR/failed-doctest-shebang.rs:9:1
   |
LL | println!("hello");
   | ----------------- caused by the macro expansion here
   |
   = note: the usage of `println!` is likely invalid in item context

error[E0601]: `main` function not found in crate `rust_out`
  --> $DIR/failed-doctest-shebang.rs:9:19
   |
LL | println!("hello");
   |                   ^ consider adding a `main` function to `$DIR/failed-doctest-shebang.rs`

error: aborting due to 2 previous errors

For more information about this error, try `rustc --explain E0601`.
Couldn't compile the test.

failures:
    $DIR/failed-doctest-shebang.rs - Foo (line 6)

test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out; finished in $TIME

Desired output

to include:

  = note: the token sequence `#!` here looks like the start of a shebang interpreter directive but it is not
  = help: if you meant this to be a shebang interpreter directive, move it to the very start of the file


See also #137619.

Rationale and extra context

See #137249

Other cases

Potential variants:
- With `main`
- With and without merging

Potentially frontmatter

Rust Version

rustc 1.92.0-nightly (4068bafed 2025-10-20)

Anything else?

No response

[epage]

#137249 (comment)

@epage Right, that's because we unfortunately strip shebang and frontmatter in doctests now … accidentally, CC #147014.

I would create a new issue. It does depend on how we want to solve #147014: If revert to the previous behavior of not stripping these, then PR #137619 should kick in. If we don't, then this diagnostic issue remains and we should do something about it (I'm omitting some other considerations).

So opening a new issue is a safe choice regardless (I might do so later unless you're faster).