temps-split-module
Mechanically split a large Rust source file (a "god file") into a module directory with no behaviour change - move-only commits, pub use re-exports that keep the public API, impl blocks spread across submodules, narrow pub(super)/pub(crate) visibility, a sibling tests.rs for oversized inline tests, and the rule-drift and test-count checks that prove nothing changed. Use when a file is over ~3,000 production lines, when inline tests push it past ~1,500 lines, or when asked to split or reorganise a module.
gotempsh · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add gotempsh/temps --skill temps-split-moduleAbout this skill
name: temps-split-module description: Mechanically split a large Rust source file (a "god file") into a module directory with no behaviour change - move-only commits, pub use re-exports that keep the public API, impl blocks spread across submodules, narrow pub(super)/pub(crate) visibility, a sibling tests.rs for oversized inline tests, and the rule-drift and test-count checks that prove nothing changed. Use when a file is over ~3,000 production lines, when inline tests push it past ~1,500 lines, or when asked to split or reorganise a module.
Split a large module
Rust lets one type have several impl blocks in different modules of the same
crate, so most god files can be split by moving code only: no renamed
functions, no changed signatures, no "while I'm here" fixes. A move-only diff is
cheap to review; a mixed one is not.
Context: docs/plans/crates-refactor-plan.md §4 P2 lists the target files and
proposed modules; §7 decisions 1 and 2 set the test-file convention and the size
limits. Typical god files: crates/temps-providers/src/services.rs,
crates/temps-deployer/src/docker.rs.
Rules
- One file per PR, and nothing else in that PR. Fixes found while moving go in a later PR (note them in the PR description).
- No behaviour change. Same tests, same test count, same public paths.
- Keep the public API. Every path other code uses (
crate::services::Foo,temps_x::services::Foo) still resolves, viapub use. - Narrowest visibility that compiles. Never widen to
pubto make a move work. - Split by responsibility, along seams that already exist: separate trait impls, groups of methods that call each other, types and errors, helpers.
Target layout
Either form is used in this repo; follow the crate's existing style.
foo/mod.rs # module docs, shared imports, types, pub use re-exports
foo/lifecycle.rs # impl Foo { ... } - one responsibility
foo/restore.rs # impl Foo { ... }
foo/tests.rs # #[cfg(test)] mod tests; when the tests are large
Real examples:
crates/temps-error-tracking/src/services/source_map_service.rswithsource_map_service/{artifacts,build_credentials,debug_ids}.rs:mod debug_ids;pluspub use artifacts::{ArtifactAssembly, ...};in the parent, anddebug_ids.rsholdingimpl SourceMapService { pub(super) async fn symbolicate_debug_ids(..) }.crates/temps-monitoring/src/http_checks/mod.rswithautomatic.rs,secret_history.rs,transport.rs,variable_history.rs:automatic.rs,secret_history.rsandvariable_history.rsstart withuse super::*;and add animpl HttpChecksServiceblock, sharingpub(super)items.- Out-of-line tests:
crates/temps-status-page/src/lib.rsdeclares#[cfg(test)] mod tests;and the tests live incrates/temps-status-page/src/tests.rs.
Procedure
0. Record the baseline
cargo test --lib -p <crate> -- --list 2>/dev/null | grep -c ': test$'
python3 scripts/rule_drift.py --list files_over_3000_lines | grep <file>
python3 scripts/rule_drift.py --list functions_over_300_lines | grep <file>
Keep the test count; it must be identical at the end.
1. Turn the file into a directory (history-preserving)
git mv crates/<crate>/src/foo.rs crates/<crate>/src/foo/mod.rs
Commit this rename on its own (refactor(<crate>): move foo.rs to foo/mod.rs)
so git keeps the file's history and blame. Skip it if the crate uses the
foo.rs + foo/ form.
2. Move tests out first (decision 1)
If inline tests push the file past ~1,500 lines, move the whole
#[cfg(test)] mod tests { ... } body into foo/tests.rs and leave:
#[cfg(test)]
mod tests;
tests.rs starts with the SPDX header and use super::*;. Being a child of
foo, it still sees foo's private items. Tests stay beside the code, never in a
distant directory. When a later step moves code into foo/bar.rs, tests that
exercise only bar may move into bar.rs's own mod tests.
3. Extract one submodule at a time
For each responsibility:
- Create
foo/<name>.rswith the SPDX header (python3 scripts/source_attribution.py annotate <file>) anduse super::*;or explicituse super::{..}imports. - Cut the items verbatim (doc comments and attributes included) and paste
them. For methods, wrap them in
impl Type { ... }in the new file. - Declare it in
mod.rs:mod <name>;and, for anything callers outsidefoouse,pub use <name>::{Item, ..};. - Fix visibility only as far as the compiler asks:
- An item that was private in
fooand is now infoo::barbut used byfooor a sibling becomespub(super). pub(crate)only if something outsidefooin the same crate uses it.- Items that were
pubstaypuband are re-exported. - Private items left in
mod.rsare already visible to its children.
- An item that was private in
cargo check --lib -p <crate>and commit:refactor(<crate>): move <responsibility> into foo/<name>.rs.
Small commits make git diff --color-moved=dimmed-zebra show almost every line
as moved; review that before pushing.
4. Keep the rule-drift counts flat
scripts/rule_drift.py counts some metrics per line, so a move can raise a
count without changing behaviour:
anyhow_in_librarycounts every line that mentionsanyhow. Repeatinguse anyhow::Result;in each new submodule raises it. Import through the parent (use super::*;) instead.handler_db_accesscountsuse sea_ormlines in any path containing/handlers/or ending inhandlers.rs. Moving service code under ahandlers/directory, or duplicatingsea_ormimports there, raises it.files_over_3000_linescounts non-blank production lines after removing#[cfg(test)]items, and an out-of-line#[cfg(test)] mod x;file is not scanned. So moving tests out