rust-lang / rust-lang/rust

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

Open
#139,685 11 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

A-lints C-feature-request T-compiler T-lang
Dominant language
Rust
Stars
119k
Forks
16.1k
PR merge metrics
PR metrics pending

Description

[!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

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reproducing the inline module cases using root.rs with either module.rs or module/mod.rs, then review how rustc handles #[path] on inline modules. Done means a lint reports the shadowed file without treating it as an error, respects #[path], and has coverage for both filesystem layouts.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
compilers
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.