Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/qaware/refactobot

Automate Code Reorganizations
https://github.com/qaware/refactobot

hacktoberfest java refactoring-tools

Last synced: 8 months ago
JSON representation

Automate Code Reorganizations

Awesome Lists containing this project

README 

          
= Refactobot - Automate code reorganizations in large Java codebases.



image:https://travis-ci.org/qaware/refactobot.svg?branch=master["Build Status", link="https://travis-ci.org/qaware/refactobot"]

image:https://coveralls.io/repos/github/qaware/refactobot/badge.svg?branch=master["Coverage Status", link="https://coveralls.io/github/qaware/refactobot?branch=master"]

image:http://img.shields.io/badge/license-MIT-green.svg?style=flat["License"]



Moving or renaming individual classes is a no-brainer in today's IDEs. But what if you want to rename thousands of

classes in hundreds of packages? What if you want to reorganize a large codebase into a new module structure?



Refactobot takes a codebase and some transformations, and applies them to the codebase fully automatically,

adapting all references. Transformations may include changing class and package names

and moving classes between packages and modules (in a multi-module build). Transformations

are programmed in a very simple Kotlin DSL.



== Features



Automated and fast::

  Transforming a codebase just means running a script, and processes thousands of classes within seconds. This means

  you can reliably reproduce the transformation as many times as needed, as the codebase is still undergoing changes.



Fully preserves formatting, whitespace, and comments::

  Refactobot only touches references to classes, when they are renamed or moved. All other code and formatting remains

  exactly as it is.



Declarative and powerful transformation language::

  Transformations are expressed declaratively in a Kotlin-based DSL. Be it simple move commands, regex-based matching,

  or custom scripting (in Kotlin) -- refactoring scripts usually are just a few lines of simple code.



Structure101 class map import::

  If you use Structure 101 for planning your refactoring, you can directly export a class map and apply it using Refactobot.

  If you have a class map from some other source, it should be simple to load.



Battle-tested::

  Refactobot was used successfully to establish a completely revamped module structure for a 200kloc codebase, which

  involved moving almost every class to a new place, and introduce uniform naming and packaging conventions.



Hackable::

  Since every codebase is different, some adaptation may be needed in some cases. Refactobot is easily extensible

  due to its modular design. On the other hand, do not expect a polished product-like experience. This is for developers!



== Usage Examples



Refactobot has no command line interface and is simply invoked from Kotlin code via its simple API.

You can find a working test case in `FullIntegrationTest`, which you can use as a start and adapt to your use case.

Below are some examples that illustrate the DSL.



=== 1) Rename some classes, based on regular expressions



If you want to change some class naming schemes, you can use regular expressions

on the class name:



[source,kotlin]

----

val refactobot = Refactobot.configure { // Create and configure the refactobot instance.



    refactor { // In this block, we specify the transformations to apply to the codebase.

        renameFile("""(.*)DaoBean\.java""" to "$1DaoImpl.java")

    }

}



refactobot.run("/path/to/codebase") // The actual invocation of the tool.

----



=== 2) Fix the base package name



This example shows how you can express your transformation in simple Kotlin code, which operates on the

file name and path:



[source,kotlin]

----

val oldBasePackage = "org/example/legacybasepackage/"

val newBasePackage = "org/example/newbasepackage/"



val refactobot = Refactobot.configure {



    refactor {



        if (this.path.startsWith(oldBasePackage)) {

            this.path = newBasePackage + this.path.removePrefix(oldBasePackage)

        }

    }

}



refactobot.run("/path/to/codebase")

----



=== 3) Apply a mapping between class names



If you have a map with fully qualified class names, you can use it like this:



[source,kotlin]

----

val refactobot = Refactobot.configure {



    refactor {

        applyClassMap(mapOf(

            "org.example.codebase.SomeClass" to "org.example.codebase.NewClassName",

            "org.example.codebase.SomeOtherClass" to "org.example.codebase.ShinyNewOtherClassName"

        ))

    }

}



refactobot.run("/path/to/codebase")

----



Alternatively, if you developed that map with Structure 101, you can import the XML file exported from there:



[source,kotlin]

----

val refactobot = Refactobot.configure {



    refactor {

        applyClassMap(Structure101ClassmapReader.readClassmapXml("classmap.xml"))

    }

}



refactobot.run("/path/to/codebase")

----



== Assumptions and Limitations



A tool cannot do everything by magic, so there are a few limitations that you should be aware of:



Build-tool-agnostic::

  Refactobot understands Java, but it does not know (or care about) your build tool, except when discovering module

  names and directories in a codebase. It was used on a multimodule Maven project, but can equally handle Gradle

  and other build tools. Of course this means that you must manually handle any necessary changes to your build files,

  e.g., when module dependencies change.



Some sane Java conventions::

  Some conventions are industry standard in the Java community, although they are not enforced by the Java compiler.

  Refactobot relies on these conventions nevertheless. If your codebase violates them, you may think about fixing this

  first. When detecting such a case, Refactobot tries to give helpful error messages. In particular, we require that:

  * The directory structure reflects the package structure, i.e., files under `foo/bar` belong to package `foo.bar`.

  * Each file contains exactly one top-level type (class, interface, enum, ...).

  * Type names start with capital letters. Package names start with small letters.



No *-imports::

  Currently, *-imports are not supported. I found it easy to work around this, since many IDEs now support expanding

  *-imports automatically.