New lint: definition_in_module_root

[corygabrielsen]

View all comments

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]

[rustbot]

r? @samueltardieu

rustbot has assigned @samueltardieu.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

Why was this reviewer chosen?

The reviewer was selected based on:

• Owners of files modified in this PR: 7 candidates
• 7 candidates expanded to 7 candidates
• Random selection from Jarcho, dswij, llogiq, samueltardieu

[github-actions]

Lintcheck changes for 518f8ea

Lint	Added	Removed	Changed
clippy::definition_in_module_root	7556	0	0

This comment will be updated if you push new changes

[samueltardieu]

Please trim the PR description. LLM generated description are overly verbose and take more time to review than it takes to generate, this is not normal.

View changes since this review

[rustbot]

Reminder, once the PR becomes ready for a review, use @rustbot ready.

[rustbot]

This lint has been nominated for inclusion.

A FCP topic has been created on Zulip.

[corygabrielsen]

Please trim the PR description. LLM generated description are overly verbose and take more time to review than it takes to generate, this is not normal.

View changes since this review

I have trimmed the PR description.

I apologize if this came off as slop. I actually spent quite a bit of time writing it because I wanted to present the mathematical motivation for the lint. I felt that it would help contextualize what I felt was the necessity of the rule and what motivated me to draft the PR.

The important snippet from the original PR description can be seen below. I wrote a good portion of this, but of course yes, the AI helped me fill it out better than I could have my self.

Mathematical Motivation for this rule

## Canonical layouts

Mathematical motivation.

This lint's value is more than stylistic. Combined with the convention of
naming each file after its primary definition, definition_in_module_root
collapses the remaining degrees of freedom in Rust's module-to-file mapping
so that the file layout is uniquely determined by the module tree.

The freedom problem

Given N symbols to organize into files, most partitions retain
combinatorial ambiguity: (N choose K) > 1 for 1 < K < N. Of all groupings,
only two are unambiguous: all symbols in one file, or one file per symbol.
The rest involve arbitrary choices about which symbols share a file with
which. The one-per-symbol extreme is the only scalable choice that
preserves canonicality.

Even under one-per-symbol, a residual freedom remains: a definition can
live in its parent's mod.rs or in a named sibling file. This lint
removes that last freedom — every definition goes in a named file. Once
both pins are in place, the filesystem tree is a direct projection of
the module tree: different authors converge on structurally identical
code, merges flatten, and automated refactoring becomes tractable.

Formal interaction with module_inception

The interaction noted in the previous section is the formal expression of
this property. Consider:

C1 (this lint):        mod.rs files hold only declarations.
C2 (module_inception): no module foo contains a child module foo.

For any type whose name matches its parent module's name, C1 ∧ C2 is
unsatisfiable:

1. C1 forbids that type in foo/mod.rs.
2. The one-name-per-file convention places it in a file named after the
   type — here, foo.rs.
3. As a sibling of foo/, that file is foo/foo.rs.
4. C2 forbids foo/foo.rs.

From ¬(C1 ∧ C2) it follows that any project enforcing C1 must accept ¬C2
for the relevant class — i.e., allow(module_inception) for types whose
name matches their parent module's name. The choice between dropping C1
or C2 is not symmetric: C1 is strictly stronger than C2, since
module_inception's premise (that definitions in mod.rs are
acceptable) is exactly what C1 denies.

Therefore the canonical-layout property requires this lint. C1 is
the load-bearing constraint; without enforcement of "declarations-only
in mod.rs," the whole property collapses to convention. The PR
provides C1; allow(module_inception) for the matching-name class is
the cost of that choice; canonical layouts are the payoff.

Portability and the codegen gap

The structural role of mod.rs is shared across module systems —
Python's __init__.py, TypeScript's index.ts, and Rust's mod.rs all
serve as the parent-as-table-of-contents file. The canonicality property
described above is therefore portable: enforce "declarations only" in
those slots in any language, and the layout becomes uniquely determined.

This matters for code-generation pipelines that target multiple languages
— schema- or IDL-driven generators that emit corresponding implementations
from one source of truth. For canonical layouts to hold across the
generated code, each target language needs its own enforcement of the
rule. Until this PR, Rust's slot was empty. Landing this lint fills it.

[corygabrielsen]

@rustbot ready

[samueltardieu]

I think this can be merged soon. However, this will be part of Rust 1.98.0.

View changes since this review

[corygabrielsen]

@rustbot ready

[rustbot]

This PR was rebased onto a different master commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

[samueltardieu]

Sorry this took so long.

Could you amend the commit for "1.99.0" and force-push? You can merge the PR afterwards.

@rustbot delegate

View changes since this review

[rustbot]

✌️ @corygabrielsen, you can now merge this pull request!

If @samueltardieu told you to merge after making some further change, then please make that change and post @rustbot merge.

View changes since this delegation

[samueltardieu]

(since you were so fast to push the updated commit I was able to enable the merge myself, no need to do it)