# Refactor a legacy module in Rust with Atlas (2026) > Atlas refactors a legacy Rust module by enumerating every callsite with the lsp tool's findReferences before it edits, then proving behavior with cargo test after each apply_patch hunk. To refactor a legacy Rust module with Atlas, enumerate every callsite before you touch anything. Atlas maps the module's public surface with the lsp tool's documentSymbol operation, then runs findReferences on each exported symbol, so a pub fn buried in src/legacy/mod.rs is traced to every use across the cargo workspace. Atlas then pins behavior by running cargo test through bash and recording the green baseline, restructures with apply_patch, which anchors on context lines and refuses to apply against a drifted file, and re-runs cargo test after each hunk lands rather than once at the end. rustfmt keeps the restructured module consistent with the rest of the crate, and cargo builds the whole thing. The risk in a Rust refactor is silent breakage at a callsite you did not know about, and findReferences is what closes that gap. ## Key takeaways - The lsp tool's documentSymbol maps a Rust module's pub surface; findReferences enumerates every callsite before a single line changes. - cargo test establishes the green baseline; without it a Rust refactor has no proof it preserved behavior. - apply_patch anchors on context lines and fails with Failed to find context if the file has drifted, so a stale hunk errors instead of miswriting src/legacy/mod.rs. - Re-run cargo test after each hunk, so a borrow-checker error is attributed to the hunk that caused it rather than to the whole refactor. - Atlas snapshots file changes as git patches so edits can be diffed and rolled back, and rustfmt normalizes the restructured crate at the end. ## How does Atlas find every caller of a Rust module before refactoring it? Atlas maps a legacy Rust module's public surface with the lsp tool's documentSymbol operation, then runs findReferences on each exported symbol to enumerate every callsite. In a 2026 cargo workspace that means every pub fn, pub struct, and pub trait in src/legacy/mod.rs is traced to every use across every crate. The risk in a Rust refactor is silent breakage at a callsite you did not know about, and grep is a poor substitute for the compiler's view. A pub fn parse_config in src/legacy/mod.rs might be re-exported through a pub use in src/lib.rs, called from a benchmark in benches/, used in a doc test, and referenced from a sibling crate in the same cargo workspace. Atlas closes that gap with the lsp tool's findReferences before it touches anything. documentSymbol enumerates what the module exposes, findReferences enumerates who depends on each item, and the union of those two lists is the true blast radius. Atlas records the remaining callsites in a todowrite list, so a partially migrated module cannot be mistaken for a finished one. ## Why run cargo test before changing a Rust module? Atlas pins behavior first: it runs the existing tests with bash and records the green baseline before changing anything. In Rust that means cargo test, including the unit tests inside #[cfg(test)] mod tests and the integration tests under tests/. Without a recorded green baseline in 2026, a refactor cannot prove it preserved behavior. A refactor is defined by behavior preservation, so the baseline is the definition of done. Atlas runs cargo test through the bash tool and records what passes today: 142 passing, 3 ignored, 0 failing, whatever the crate actually reports. Rust makes this easier than most languages because #[cfg(test)] mod tests lives inside src/legacy/mod.rs itself, so the tests that cover the module you are about to gut are usually in the same file you are about to edit. Atlas reads them first with read. If the legacy module has no tests at all, the honest answer is that the refactor has no safety net, and Atlas will surface that rather than proceed as if cargo test were meaningful. Restructure with apply_patch only after the baseline exists. ## What does apply_patch do that a plain edit does not in Rust? Atlas restructures Rust with apply_patch, which seeks each hunk's context and old_lines and fails with Failed to find context if the file has drifted. In a legacy module where you are moving 6 impl blocks across src/legacy/mod.rs and a new src/config/parser.rs, that anchoring is what stops a hunk landing in the wrong place. apply_patch anchors on context lines, which is the right property for a structural Rust refactor. When you split a 900-line src/legacy/mod.rs into a mod tree, you are applying many hunks in sequence, and each one shifts the line numbers under the next. A patch tool that trusted line offsets would corrupt the file by hunk three. apply_patch instead seeks each hunk's context and old_lines and fails with Failed to find context if the file has drifted, so a stale hunk is a loud error rather than a quiet miswrite. Atlas computes a unified diff for every file edit and surfaces it for approval before writing, so you see each hunk before it lands, and Atlas snapshots file changes as git patches so edits can be diffed and rolled back if the split turns out to be wrong. ## How do you know a Rust refactor did not break the borrow checker? Atlas re-runs the tests with bash after each hunk lands, not once at the end. In Rust the compiler is the first line of defense: cargo build fails on a borrow-checker or lifetime error before cargo test even runs, so a 2026 refactor that moves ownership across a module boundary is caught in seconds, not in review. Moving code between Rust modules changes lifetimes in ways that are not obvious from the diff. Hoisting a struct out of src/legacy/mod.rs into its own file can turn a field borrow into a cross-module borrow the checker rejects, and adding a pub can change the required lifetime bounds on a trait impl. Atlas runs cargo through bash after every hunk, so the borrow-checker error is attributed to the hunk that caused it rather than to the whole refactor. Atlas is built to work through the borrow checker, cargo, and clippy lints, and the after-each-hunk cadence is what makes that tractable. Run rustfmt once the structure settles, and keep the remaining callsites in the todowrite list until findReferences returns zero hits on the old path. ## How does Atlas keep a large Rust refactor reviewable? Atlas keeps a large Rust refactor reviewable by tracking the remaining callsites in a todowrite list, so a partially migrated module cannot be mistaken for a finished one. Combined with a unified diff per file edit and a git patch snapshot per change, a 40-callsite migration across a cargo workspace stays auditable in 2026. A legacy Rust refactor is rarely one commit. Atlas records each callsite from findReferences as a todowrite entry, marks it done only after cargo test passes with that callsite migrated, and leaves the rest pending. Atlas reads git branches, status, and diffs, and can stage and create commits on your behalf, so the refactor becomes a series of small, green commits rather than one enormous unreviewable patch. Every Atlas tool call is permission-gated against allow, ask, and deny rules before it runs, so the bash invocations of cargo test and cargo build, and every apply_patch against src/, are all things you approved. The end state is a restructured module, a green cargo test, clean rustfmt output, and zero remaining references to the old path. ## Steps 1. Run atlas in a crate with a Cargo.toml so Atlas can read your modules, traits, and cargo workspace. 2. Map the legacy module's public surface with the lsp tool's documentSymbol operation, listing every pub fn, pub struct, and pub trait in src/legacy/mod.rs. 3. Run findReferences on each exported symbol to enumerate every callsite, including re-exports through pub use in src/lib.rs and uses in tests/ and benches/. 4. Pin behavior first: run cargo test with the bash tool and record the green baseline before changing anything. 5. Restructure with apply_patch, which seeks each hunk's context and old_lines and fails with Failed to find context if the file has drifted. 6. Re-run cargo test with bash after each hunk lands, not once at the end, so a borrow-checker or lifetime error is attributed to the hunk that caused it. 7. Track the remaining callsites in a todowrite list so a partially migrated module cannot be mistaken for a finished one. 8. Run rustfmt once the structure settles, then review the diff before cargo build and commit. ## FAQ ### how to safely refactor a legacy Rust module without breaking callers Enumerate the callers first. Atlas maps the module's public surface with the lsp tool's documentSymbol operation, then runs findReferences on each exported symbol, so every use across the cargo workspace is known before apply_patch touches src/legacy/mod.rs. ### what is apply_patch in Atlas and why not just use edit apply_patch seeks each hunk's context and old_lines and fails with Failed to find context if the file has drifted. For a structural Rust refactor where hunks shift line numbers under each other, that anchoring is what prevents a hunk landing in the wrong place. ### how do I get an AI agent to run cargo test between edits Atlas re-runs the tests with bash after each hunk lands, not once at the end. In Rust that means cargo test after every apply_patch, so a failure is attributed to the specific hunk that caused it. ### can Atlas find every use of a pub fn in a cargo workspace Yes. The lsp tool's findReferences operation returns the authoritative reference set from the Rust language server, which catches re-exports through pub use, uses in tests/ and benches/, and callers in sibling crates that grep would miss or wrongly match. ### does Atlas help with borrow checker errors during a refactor Atlas pairs with Rust to work through the borrow checker, cargo, and clippy lints. Running cargo build and cargo test through bash after each hunk means a lifetime or ownership error introduced by moving a struct across a module boundary is caught immediately. ### how do I undo an AI refactor that broke my Rust crate Atlas snapshots file changes as git patches so edits can be diffed and rolled back. If cargo test goes red halfway through restructuring src/legacy/mod.rs, the applied hunks can be reverted rather than manually unpicked. ### how do I track progress through a multi-callsite Rust migration Atlas tracks the remaining callsites in a todowrite list so a partially migrated module cannot be mistaken for a finished one. Each callsite is marked done only after cargo test passes with that callsite migrated. --- Canonical HTML: https://runatlas.sh/resources/stacks/refactor-a-legacy-module-in-rust Source of truth: aeo_pages row `/resources/stacks/refactor-a-legacy-module-in-rust` (segment: Stacks) (this file is generated from it, never hand-edited). Licence: Atlas is proprietary with a free core. It is not open source and there is no public source repository.