Lint on inline modules `module` if there also exists a file at path `./module.rs` or `./module/mod.rs`

[iyernaveenr]

Note

The updated description was written by @fmease.

---

Given the following code in a file called root.rs:

mod module { /*…*/ }

and a file structure of the form:

.
├── root.rs
└── module.rs  (empty)

or

.
├── root.rs
└── module/
    └── mod.rs  (empty)

it could be beneficial if rustc could feature a lint that informs the user that the files module.rs and module/mod.rs respectively are not considered since they are essentially shadowed by the inline module.

In real code bases, this situation might arise when the user has updated a file module declaration mod module; to mod module { /*…*/ } while forgetting to copy over the contents of the former module file or forgetting to delete it.

Since the proposed lint would be relatively expensive to run due to the extra filesystem-related syscalls per inline module, it should maybe be allow-by-default only?

The lint should take into account #[path] (indeed, it's intentionally allowed on inline modules, cc #13156).

---

Original outdated issue description

In Chapter 7 of rustbook, Section 7.2 -> Modules Cheat Sheet -> Declaring modules:, the preference of the compiler for module declarations is clearly defined. However, when I tried experimenting with all the three ways, namely:
1 of 3) Inline, within curly brackets that replace the semicolon following mod garden
2 of 3) In the file src/garden.rs
3 of 3) In the file src/garden/mod.rs
I observed inconsistency in the compiler's behaviour when using multiple ways.

To check how these three ways might conflict with each other, I first tried 1 of 3) and 2 of 3) above. The behaviour of the compiler was to silently (as in, no error or warning) prefer 1 of 3) over 2 of 3), effectively ignoring 2 of 3). So, the compilation was successful.

However, when I tried 2 of 3) and 3 of 3), the compiler threw error[E0761], complaining about the module being found in multiple places.

Code (1 of 3) and 2 of 3))

restaurant$ tree
.
├── Cargo.lock
├── Cargo.toml
└── src
    ├── front_of_house
    │   └── hosting.rs
    ├── front_of_house.rs
    ├── lib.rs
    └── main.rs

2 directories, 6 files

restaurant$ cat Cargo.toml 
[package]
name = "restaurant"
version = "0.1.0"
edition = "2021"

[dependencies]

restaurant$ cat src/main.rs 
use restaurant::eat_at_restaurant;

fn main() {
    println!("{}:{}: Hello, world!", file!(), line!());
    eat_at_restaurant();
}

restaurant$ cat src/lib.rs 
mod front_of_house;

pub use crate::front_of_house::hosting;

pub fn eat_at_restaurant() {
    hosting::add_to_waitlist();

restaurant$ cat src/front_of_house.rs 
pub mod hosting {
    pub fn add_to_waitlist() {
        println!("{}:{}: I was called!", file!(), line!());
    }
}

restaurant$ cat src/front_of_house/hosting.rs 
pub fn add_to_waitlist() {
    println!("{}:{}: I was called!", file!(), line!());
}

restaurant$ cargo run
   Compiling restaurant v0.1.0 (/media/nibu/ext4_data/ext4_progprac/Basics/restaurant)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.16s
     Running `target/debug/restaurant`
src/main.rs:4: Hello, world!
src/front_of_house.rs:3: I was called!

Code (2 of 3) and 3 of 3))

restaurant$ tree
.
├── Cargo.lock
├── Cargo.toml
└── src
    ├── front_of_house
    │   ├── hosting
    │   │   └── mod.rs
    │   └── hosting.rs
    ├── front_of_house.rs
    ├── lib.rs
    └── main.rs

3 directories, 7 files

restaurant$ cat Cargo.toml 
[package]
name = "restaurant"
version = "0.1.0"
edition = "2021"

[dependencies]

restaurant$ cat src/main.rs 
use restaurant::eat_at_restaurant;

fn main() {
    println!("{}:{}: Hello, world!", file!(), line!());
    eat_at_restaurant();
}

restaurant$ cat src/lib.rs 
mod front_of_house;

pub use crate::front_of_house::hosting;

pub fn eat_at_restaurant() {
    hosting::add_to_waitlist();

restaurant$ cat src/front_of_house.rs 
pub mod hosting;

restaurant$ cat src/front_of_house/hosting.rs 
pub fn add_to_waitlist() {
    println!("{}:{}: I was called!", file!(), line!());
}

restaurant$ cat src/front_of_house/hosting/mod.rs 
pub fn add_to_waitlist() {
    println!("{}:{}: I was called!", file!(), line!());
}

restaurant$ cargo run
   Compiling restaurant v0.1.0 (/home/user/restaurant)
error[E0761]: file for module `hosting` found at both "src/front_of_house/hosting.rs" and "src/front_of_house/hosting/mod.rs"
 --> src/front_of_house.rs:1:1
  |
1 | pub mod hosting;
  | ^^^^^^^^^^^^^^^^
  |
  = help: delete or rename one of them to remove the ambiguity

error[E0425]: cannot find function `add_to_waitlist` in module `hosting`
 --> src/lib.rs:6:14
  |
6 |     hosting::add_to_waitlist();
  |              ^^^^^^^^^^^^^^^ not found in `hosting`

Some errors have detailed explanations: E0425, E0761.
For more information about an error, try `rustc --explain E0425`.
error: could not compile `restaurant` (lib) due to 2 previous errors

Meta

rustc --version --verbose:

rustc 1.84.0-nightly (32b17d56e 2024-10-28)
binary: rustc
commit-hash: 32b17d56eb02495f9865028e1f7271a3a48c0b9b
commit-date: 2024-10-28
host: x86_64-unknown-linux-gnu
release: 1.84.0-nightly
LLVM version: 19.1.1

[fmease]

The compiler works perfectly fine here, the phrasing of the book is just ambiguous. These three options are simply mutually exclusive and the book doesn't make it clear.

@rustbot transfer book

[rustbot]

Failed to transfer issue:
error: rustbot does not have the correct permissions to execute TransferIssue

[fmease]

Please open an issue over at https://github.com/rust-lang/book/issues/ instead unless it's already been reported there.