New lint: definition_in_module_root (#16965)

*[View all
comments](https://triagebot.infra.rust-lang.org/gh-comments/rust-lang/rust-clippy/pull/16965)*

Adds a restriction lint that flags item definitions (struct, enum, fn,
impl, trait, etc.) in `mod.rs` files, so `mod.rs` is reserved for
declarations and re-exports.

- `lib.rs` and `main.rs` are not checked
- `#[macro_export]` macros and macro-expanded items are skipped
- `#[path]` is resolved via the source map

changelog: new lint: [`definition_in_module_root`]

Author: samueltardieu

CHANGELOG.md

@@ -6840,6 +6840,7 @@ Released 2018-09-13
 [`default_numeric_fallback`]: https://rust-lang.github.io/rust-clippy/master/index.html#default_numeric_fallback
 [`default_trait_access`]: https://rust-lang.github.io/rust-clippy/master/index.html#default_trait_access
 [`default_union_representation`]: https://rust-lang.github.io/rust-clippy/master/index.html#default_union_representation
+[`definition_in_module_root`]: https://rust-lang.github.io/rust-clippy/master/index.html#definition_in_module_root
 [`deprecated_cfg_attr`]: https://rust-lang.github.io/rust-clippy/master/index.html#deprecated_cfg_attr
 [`deprecated_clippy_cfg_attr`]: https://rust-lang.github.io/rust-clippy/master/index.html#deprecated_clippy_cfg_attr
 [`deprecated_semver`]: https://rust-lang.github.io/rust-clippy/master/index.html#deprecated_semver

clippy_lints/src/declared_lints.rs

@@ -97,6 +97,7 @@ pub static LINTS: &[&::declare_clippy_lint::LintInfo] = &[
     crate::default_instead_of_iter_empty::DEFAULT_INSTEAD_OF_ITER_EMPTY_INFO,
     crate::default_numeric_fallback::DEFAULT_NUMERIC_FALLBACK_INFO,
     crate::default_union_representation::DEFAULT_UNION_REPRESENTATION_INFO,
+    crate::definition_in_module_root::DEFINITION_IN_MODULE_ROOT_INFO,
     crate::dereference::EXPLICIT_AUTO_DEREF_INFO,
     crate::dereference::EXPLICIT_DEREF_METHODS_INFO,
     crate::dereference::NEEDLESS_BORROW_INFO,

clippy_lints/src/definition_in_module_root.rs

@@ -0,0 +1,161 @@
+use clippy_utils::diagnostics::span_lint_and_help;
+use rustc_ast::ast::{self, Inline, ItemKind, ModKind};
+use rustc_lint::{EarlyContext, EarlyLintPass, LintContext};
+use rustc_session::impl_lint_pass;
+use rustc_span::{FileName, SourceFile, sym};
+
+declare_clippy_lint! {
+    /// ### What it does
+    /// Checks for definitions (structs, functions, traits, etc.) in `mod.rs`
+    /// files. `lib.rs` and `main.rs` are not checked.
+    ///
+    /// ### Why restrict this?
+    /// `mod.rs` is well-suited to acting as a table of contents — listing
+    /// submodules and re-exports while leaving definitions to named files.
+    /// Naming each file after its primary definition keeps filenames
+    /// descriptive and unique, makes editor tabs and search results easier
+    /// to scan, and makes the filesystem tree mirror the module tree, so
+    /// the file layout is uniquely determined by the module structure.
+    ///
+    /// ### Example
+    /// ```ignore
+    /// // stuff/mod.rs
+    /// mod bar;
+    /// pub struct Foo { /* ... */ }
+    /// impl Foo { /* ... */ }
+    /// ```
+    /// Use instead:
+    /// ```ignore
+    /// // stuff/mod.rs
+    /// mod bar;
+    /// mod foo;
+    /// pub use foo::Foo;
+    ///
+    /// // stuff/foo.rs
+    /// pub struct Foo { /* ... */ }
+    /// impl Foo { /* ... */ }
+    /// ```
+    ///
+    /// ### Notes
+    /// This lint is most useful alongside `self_named_module_files`, which
+    /// requires `mod.rs` files; together they constrain `mod.rs` to
+    /// declarations only. Under `mod_module_files` (which forbids `mod.rs`
+    /// entirely) this lint has nothing to fire on.
+    ///
+    /// If a definition's name matches its parent module's name, moving it
+    /// produces `foo/foo.rs`, which `module_inception` flags — projects
+    /// in that situation typically also `allow(module_inception)`.
+    #[clippy::version = "1.99.0"]
+    pub DEFINITION_IN_MODULE_ROOT,
+    restriction,
+    "definitions in `mod.rs` should be in named files"
+}
+
+impl_lint_pass!(DefinitionInModuleRoot => [DEFINITION_IN_MODULE_ROOT]);
+
+#[derive(Default)]
+pub struct DefinitionInModuleRoot {
+    /// Stack tracking whether items at the current nesting level are in a
+    /// `mod.rs` file. When the stack is empty, we are at crate root depth
+    /// (not linted).
+    module_stack: Vec<bool>,
+}
+
+impl EarlyLintPass for DefinitionInModuleRoot {
+    fn check_item(&mut self, cx: &EarlyContext<'_>, item: &ast::Item) {
+        // Handle module items: push state for their children.
+        match &item.kind {
+            ItemKind::Mod(.., ModKind::Loaded(_, Inline::No { .. }, mod_spans, ..)) => {
+                let file = cx.sess().source_map().lookup_source_file(mod_spans.inner_span.lo());
+                self.module_stack.push(is_mod_rs(&file));
+                return;
+            },
+            ItemKind::Mod(..) => {
+                // Inline module or unloaded — children are not in a root file.
+                self.module_stack.push(false);
+                return;
+            },
+            _ => {},
+        }
+
+        // Skip items from macro expansion.
+        if item.span.from_expansion() {
+            return;
+        }
+
+        // Only lint inside mod.rs files (not at crate root depth).
+        if !self.module_stack.last().copied().unwrap_or(false) {
+            return;
+        }
+
+        let Some(kind) = definition_kind(item) else {
+            return;
+        };
+
+        let help = if let Some(ident) = item.kind.ident() {
+            format!("move {kind} `{ident}` to a dedicated file")
+        } else {
+            format!("move the {kind} to a dedicated file")
+        };
+
+        span_lint_and_help(
+            cx,
+            DEFINITION_IN_MODULE_ROOT,
+            item.span,
+            "definition in module root file",
+            None,
+            help,
+        );
+    }
+
+    fn check_item_post(&mut self, _: &EarlyContext<'_>, item: &ast::Item) {
+        if matches!(item.kind, ItemKind::Mod(..)) {
+            self.module_stack.pop();
+        }
+    }
+}
+
+/// Returns a human-readable kind string for flagged items, or `None` for
+/// items that are allowed in root files (modules, imports, re-exports,
+/// `#[macro_export]` macros).
+fn definition_kind(item: &ast::Item) -> Option<&'static str> {
+    match &item.kind {
+        i @ (ItemKind::Struct(..)
+        | ItemKind::Enum(..)
+        | ItemKind::Union(..)
+        | ItemKind::Fn(..)
+        | ItemKind::Const(..)
+        | ItemKind::Static(..)
+        | ItemKind::Impl(..)
+        | ItemKind::Trait(..)
+        | ItemKind::TraitAlias(..)
+        | ItemKind::TyAlias(..)
+        | ItemKind::ForeignMod(..)) => Some(i.descr()),
+        i @ ItemKind::MacroDef(..) if !has_macro_export(item) => Some(i.descr()),
+        ItemKind::ExternCrate(..)
+        | ItemKind::Use(..)
+        | ItemKind::ConstBlock(..)
+        | ItemKind::Mod(..)
+        | ItemKind::GlobalAsm(..)
+        | ItemKind::MacCall(..)
+        | ItemKind::MacroDef(..)
+        | ItemKind::Delegation(..)
+        | ItemKind::DelegationMac(..) => None,
+    }
+}
+
+/// Check if an item has `#[macro_export]`.
+fn has_macro_export(item: &ast::Item) -> bool {
+    item.attrs.iter().any(|attr| attr.has_name(sym::macro_export))
+}
+
+/// Check if a source file is `mod.rs`.
+fn is_mod_rs(file: &SourceFile) -> bool {
+    if let FileName::Real(name) = &file.name {
+        name.local_path()
+            .and_then(|p| p.file_name())
+            .is_some_and(|n| n == "mod.rs")
+    } else {
+        false
+    }
+}

clippy_lints/src/lib.rs

@@ -103,6 +103,7 @@ mod default_constructed_unit_structs;
 mod default_instead_of_iter_empty;
 mod default_numeric_fallback;
 mod default_union_representation;
+mod definition_in_module_root;
 mod dereference;
 mod derivable_impls;
 mod derive;
@@ -541,6 +542,7 @@ rustc_lint::early_lint_methods!(
         CfgNotTest: cfg_not_test::CfgNotTest = cfg_not_test::CfgNotTest,
         EmptyLineAfter: empty_line_after::EmptyLineAfter = empty_line_after::EmptyLineAfter::new(),
         InlineTraitBounds: inline_trait_bounds::InlineTraitBounds = inline_trait_bounds::InlineTraitBounds::default(),
+        DefinitionInModuleRoot: definition_in_module_root::DefinitionInModuleRoot = definition_in_module_root::DefinitionInModuleRoot::default(),
         // add early passes here, used by `cargo dev new_lint`
     ]]
 );

tests/ui-cargo/definition_in_module_root/fail_edge_cases/Cargo.stderr

@@ -0,0 +1,87 @@
+error: definition in module root file
+  --> src/edge_cases/mod.rs:13:1
+   |
+13 | pub struct AboveMod;
+   | ^^^^^^^^^^^^^^^^^^^^
+   |
+   = help: move struct `AboveMod` to a dedicated file
+   = note: `-D clippy::definition-in-module-root` implied by `-D warnings`
+   = help: to override `-D warnings` add `#[allow(clippy::definition_in_module_root)]`
+
+error: definition in module root file
+  --> src/edge_cases/mod.rs:20:1
+   |
+20 | pub struct Foo;
+   | ^^^^^^^^^^^^^^^
+   |
+   = help: move struct `Foo` to a dedicated file
+
+error: definition in module root file
+  --> src/edge_cases/mod.rs:23:1
+   |
+23 | pub struct Generic<T>(T);
+   | ^^^^^^^^^^^^^^^^^^^^^^^^^
+   |
+   = help: move struct `Generic` to a dedicated file
+
+error: definition in module root file
+  --> src/edge_cases/mod.rs:24:1
+   |
+24 | / impl<T> Generic<T> {
+25 | |     pub fn new(t: T) -> Self {
+26 | |         Self(t)
+27 | |     }
+28 | | }
+   | |_^
+   |
+   = help: move the implementation to a dedicated file
+
+error: definition in module root file
+  --> src/edge_cases/mod.rs:31:1
+   |
+31 | pub async fn frob() {}
+   | ^^^^^^^^^^^^^^^^^^^^^^
+   |
+   = help: move function `frob` to a dedicated file
+
+error: definition in module root file
+  --> src/edge_cases/mod.rs:34:1
+   |
+34 | / pub const fn cnst() -> u32 {
+35 | |     0
+36 | | }
+   | |_^
+   |
+   = help: move function `cnst` to a dedicated file
+
+error: definition in module root file
+  --> src/edge_cases/mod.rs:39:1
+   |
+39 | pub static FOO: u32 = 1;
+   | ^^^^^^^^^^^^^^^^^^^^^^^^
+   |
+   = help: move static item `FOO` to a dedicated file
+
+error: definition in module root file
+  --> src/edge_cases/mod.rs:43:1
+   |
+43 | / macro_rules! local_macro {
+44 | |     () => {};
+45 | | }
+   | |_^
+   |
+   = help: move macro definition `local_macro` to a dedicated file
+
+error: definition in module root file
+  --> src/edge_cases/mod.rs:48:1
+   |
+48 | / pub trait WithDefault {
+49 | |     fn default_method(&self) -> u32 {
+50 | |         42
+51 | |     }
+52 | | }
+   | |_^
+   |
+   = help: move trait `WithDefault` to a dedicated file
+
+error: could not compile `fail-edge-cases` (lib) due to 9 previous errors

tests/ui-cargo/definition_in_module_root/fail_edge_cases/Cargo.toml

@@ -0,0 +1,5 @@
+[package]
+name = "fail-edge-cases"
+version = "0.1.0"
+edition = "2021"
+publish = false

tests/ui-cargo/definition_in_module_root/fail_edge_cases/src/edge_cases/mod.rs

@@ -0,0 +1,59 @@
+#![warn(clippy::definition_in_module_root)]
+
+// Case g: extern crate is a declaration → no fire.
+extern crate alloc;
+
+// Case b: re-export of named item from sibling → no fire.
+pub use super::other::Bar;
+
+// Case c: glob re-export → no fire.
+pub use super::other::*;
+
+// Case j (top half): item right above `mod foo;` → fires.
+pub struct AboveMod;
+
+// Case j: nested file module declaration → no fire (declaration only).
+mod sub;
+
+// Case a: derive — struct fires once, derived impls do NOT fire (from_expansion).
+#[derive(Clone, Debug)]
+pub struct Foo;
+
+// Case d: generics — struct fires + impl block fires.
+pub struct Generic<T>(T);
+impl<T> Generic<T> {
+    pub fn new(t: T) -> Self {
+        Self(t)
+    }
+}
+
+// Case e: async fn fires as 'function'.
+pub async fn frob() {}
+
+// Case f: const fn fires as 'function'.
+pub const fn cnst() -> u32 {
+    0
+}
+
+// Case h: static fires as 'static'.
+pub static FOO: u32 = 1;
+
+// Case k: non-exported macro fires as 'macro'.
+#[allow(unused_macros)]
+macro_rules! local_macro {
+    () => {};
+}
+
+// Case l: trait with default method body fires once (not its inner items).
+pub trait WithDefault {
+    fn default_method(&self) -> u32 {
+        42
+    }
+}
+
+// Case i: inline module — children should NOT fire.
+#[cfg(test)]
+mod tests {
+    pub struct InsideInline;
+    pub fn t() {}
+}

tests/ui-cargo/definition_in_module_root/fail_edge_cases/src/edge_cases/sub.rs

@@ -0,0 +1,6 @@
+// Sibling file referenced by `mod sub;` in edge_cases/mod.rs.
+// Items here live in a non-mod.rs file → no fire even if they are definitions.
+#[allow(dead_code)]
+pub struct InSub;
+#[allow(dead_code)]
+pub fn in_sub() {}

tests/ui-cargo/definition_in_module_root/fail_edge_cases/src/lib.rs

@@ -0,0 +1,4 @@
+#![warn(clippy::definition_in_module_root)]
+
+pub mod edge_cases;
+pub mod other;

tests/ui-cargo/definition_in_module_root/fail_edge_cases/src/other.rs

@@ -0,0 +1,3 @@
+// Sibling module with items that the edge_cases mod.rs re-exports.
+pub struct Bar;
+pub fn helper() {}