# Refactor a Legacy Scala Module with Atlas in 2026 > Atlas enables Scala developers to safely refactor legacy modules by mapping public APIs, verifying behavior with `sbt test`, and applying precise code changes. Atlas helps Scala developers in 2026 refactor legacy modules by mapping public surfaces, pinning behavior with `sbt test` via ScalaTest, applying structural changes with `apply_patch`, and tracking progress with `todowrite`, ensuring no breaking changes to callers. ## Key takeaways - Atlas uses `lsp` to precisely map Scala module APIs and find all callers. - Behavior is pinned by running `ScalaTest via sbt test` before and after each change. - Structural changes are applied safely with `apply_patch`, which validates file context. - Atlas tracks refactoring progress with `todowrite` for remaining Scala callsites. - Every Scala file edit generates a unified diff for explicit user approval. - Atlas integrates with `git` for robust change management and rollback capabilities. ## How to map a Scala module's public API and find callers with Atlas? Atlas maps a Scala module's public API and enumerates all its callers by leveraging the `lsp` tool's `documentSymbol` and `findReferences` operations. This crucial first step, often completed in under 5 minutes, ensures you understand the module's external dependencies before any changes are made. Before restructuring any Scala code, Atlas first builds a comprehensive understanding of the module's public surface. Using the `lsp` tool, Atlas executes `documentSymbol` on your target Scala file, such as `src/main/scala/com/example/LegacyModule.scala`, to identify all exported traits, classes, objects, and methods. For each identified symbol, Atlas then runs `lsp findReferences` across your entire `sbt` project. This process precisely enumerates every single callsite, providing a complete picture of where the legacy module is being used. This detailed mapping prevents silent breakage at unknown callsites, a common risk in refactoring efforts. ## How does Atlas ensure no behavior changes in Scala refactoring? Atlas ensures no behavior changes during Scala refactoring by strictly pinning the module's existing behavior. It achieves this by running your `ScalaTest via sbt test` suite and recording a green baseline, a process that typically takes less than 10 seconds for a well-configured project. The core principle of safe refactoring is to prove that the module's external behavior remains unchanged. Atlas achieves this by integrating directly with your Scala project's existing test suite. Before any code modifications, Atlas executes `atlas bash "sbt test"`. This command runs all tests defined in files like `src/test/scala/com/example/LegacyModuleSpec.scala` using ScalaTest. Atlas records the output, establishing a 'green baseline' that confirms all existing tests pass. After each subsequent structural change, Atlas re-runs `atlas bash "sbt test"` to immediately verify that the module's behavior has not inadvertently shifted, providing continuous validation throughout the refactoring process. ## How does Atlas apply structural changes safely to Scala code? Atlas applies structural changes to Scala code with high precision using its `apply_patch` tool, which anchors on context lines and refuses to apply against a drifted file. This mechanism prevents unintended modifications, ensuring that a patch intended for a specific code state in 2026 only applies to that exact state. When it's time to restructure the Scala module, Atlas uses the `apply_patch` tool. This tool is designed for robust and safe code modification. Instead of blindly overwriting lines, `apply_patch` seeks each hunk's context and old_lines within the target file, such as `src/main/scala/com/example/LegacyModule.scala`. If the file has drifted,meaning the context lines or old lines no longer match,`apply_patch` will fail with a 'Failed to find context' error. This prevents applying a patch to an outdated or modified version of the file, safeguarding against accidental corruption. After each successful hunk application, Atlas immediately re-runs `atlas bash "sbt test"` to confirm that the change did not introduce regressions, maintaining a continuous cycle of change and verification. ## How does Atlas track refactoring progress and ensure code review for Scala? Atlas tracks refactoring progress and ensures thorough code review for Scala projects by maintaining a `todowrite` list of remaining callsites and presenting a unified diff for every file edit. This transparent approach ensures that all 100% of changes are reviewed and approved before being written to disk. Throughout the refactoring of a Scala module, Atlas provides mechanisms for tracking progress and ensuring rigorous review. The `todowrite` tool is used to maintain a list of remaining callsites that still need migration, preventing a partially refactored module from being mistaken for a finished one. For every proposed file edit, Atlas computes a unified diff, clearly showing the changes to files like `src/main/scala/com/example/LegacyModule.scala` or `build.sbt`. This diff is surfaced for your approval before Atlas writes any changes to disk. Furthermore, Atlas reads `git` branches, status, and diffs, and can stage and create commits on your behalf, allowing for easy rollback of edits via `git patches` if needed, ensuring a controlled and auditable refactoring workflow. ## Steps 1. Map the Scala module's public surface: Use `atlas lsp documentSymbol` on your target Scala file (e.g., `src/main/scala/com/example/LegacyModule.scala`) to identify all exported symbols. 2. Enumerate all callers: For each identified symbol, run `atlas lsp findReferences` across your `sbt` project to list every callsite. 3. Pin behavior: Execute `atlas bash "sbt test"` to run your ScalaTest suite and record a green baseline, ensuring all existing tests pass before any changes. 4. Restructure with precision: Apply structural changes to your Scala files (e.g., `src/main/scala/com/example/LegacyModule.scala`) using `atlas apply_patch`, which anchors on context lines and will fail if the file has drifted. 5. Verify after each change: Immediately re-run `atlas bash "sbt test"` after each `apply_patch` hunk lands to confirm that the module's behavior remains unchanged. 6. Track remaining work: Use `atlas todowrite` to keep a list of any remaining callsites that still need to be migrated or updated, ensuring a complete refactor. 7. Review and approve: Review the unified diff presented by Atlas for every file edit and approve the changes before they are written to disk. ## FAQ ### How does Atlas integrate with sbt for Scala projects? Atlas runs `sbt` commands directly via its `bash` tool, allowing it to execute `sbt test` for ScalaTest, manage dependencies, and interact with your project's build lifecycle. It operates within your existing `build.sbt` configured environment. ### Can Atlas refactor Scala implicits or typeclasses? Yes, Atlas can refactor to typeclasses or add ScalaTest cases. It leverages its AST indexing with tree-sitter to understand Scala's structural elements like traits, implicits, and typeclasses, enabling intelligent transformations. ### What happens if Atlas's patch fails to apply to my Scala file? If a Scala file has drifted, Atlas's `apply_patch` tool will fail with 'Failed to find context'. This prevents unintended changes to a modified file, requiring you to resolve the drift or re-evaluate the patch before proceeding. ### How does Atlas ensure my Scala code stays formatted during refactoring? While Atlas focuses on structural changes, you can integrate `scalafmt` into your workflow by running `atlas bash "scalafmt"` after changes, or configure your `build.sbt` to apply formatting on compile, ensuring consistent code style. ### How does Atlas handle large Scala codebases for refactoring? Atlas indexes code by AST declarations using tree-sitter, not blind line windows, allowing it to understand the precise structure of large Scala codebases. It also uses hybrid semantic and keyword retrieval fused by reciprocal rank fusion for efficient and accurate searching. ### Is it possible to roll back changes made by Atlas to Scala files? Yes, Atlas snapshots file changes as `git patches` so edits can be diffed and rolled back. It also reads `git` branches and status, and can stage and create commits on your behalf, providing full version control integration. --- Canonical HTML: https://runatlas.sh/resources/stacks/refactor-a-legacy-module-in-scala Source of truth: aeo_pages row `/resources/stacks/refactor-a-legacy-module-in-scala` (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.