CleanThat

Cleanthat is a project enabling automatic code cleaning, from formatting to refactoring.

MUTATORS.generated.MD

The point of this project is to enable automatic cleaning of your code-base. By cleaning, we include :

1. formatting (with an Eclipse stylesheet, Google-Java-Format, etc)
2. linting (given any IMutator)
3. refactoring (WIP)
4. migrating (from JUnit4 to JUnit5)

As of 2022-12, it focuses on Java projects, but enabling formatting various languages through Spotless.

Related projects:

• https://jsparrow.github.io/ (paid)
• https://github.com/JnRouvignac/AutoRefactor (free)
• https://github.com/openrewrite/rewrite-migrate-java (free)
• https://www.moderne.io/ (paid)
• https://eslint.org/docs/latest/extend/custom-formatters (free)
• https://errorprone.info/docs/refaster (free)
• https://github.com/walkmod/walkmod-pmd-plugin (free)
• https://github.com/XenoAmess/remove-unused-imports-maven-plugin (free, focused on imports)
• https://github.com/SpoonLabs/sorald (free)
• https://github.com/redhat-developer/vscode-java/blob/master/document/_java.learnMoreAboutCleanUps.md (free)
• Academic papers

See CHANGES.MD

• 2023-03-23: 2.12 Latest release
• ...
• 2023-02-06: 2.0 Major Release leveraging from/to Spotless
• ...
• 2021-08-12: 1.0 Initial Release

Cleanthat Robot is currently compatible with the following languages:

• java (Spotless and OpenRewrite)
• pom.xml (Spotless)
• json (Spotless)
• xml (Spotless)
• yaml (Spotless)
• kotlin (Spotless)

see FormatterFactory

Cleanthat Refactorer is currently compatible with the following languages:

• java (Cleanthat)
• java (OpenRewrite)
• java (Eclipse Cleanup)

• CleanThat processes files individually, which indices limited Type resolution. This enables cleaning files on a per-impacted-file basis (e.g. in a Github Pull-Request).
• The type resolution may be lifted through cleanthat-maven-plugin (TODO)
• The project jhas poor support of charset others than UTF-8

mvn integration is available through Spotless: https://github.com/diffplug/spotless/tree/main/plugin-maven#cleanthat

One can then clean its codebase with mvn spotless:apply

See README: https://github.com/solven-eu/cleanthat/tree/master/maven

(https://mvnrepository.com/artifact/io.github.solven-eu.cleanthat/cleanthat-maven-plugin)

Features :

• Apply full refactoring as it would be executed by the Github App, based on .cleanthat configuration
• Generate automatically an optimal Eclipse stylesheet based on your code-case

One liner (even without a pom.xml):

    mvn io.github.solven-eu.cleanthat:cleanthat-maven-plugin:cleanthat

or simply mvn cleanthat:apply

gradle integration is available through Spotless: https://github.com/diffplug/spotless/tree/main/plugin-gradle#cleanthat

If your repository is hosted by Github.com, get zero-configuration cleaning with our Github App on Github marketplace.

It can configured through a /.cleanthat/cleanthat.yaml file at the root of the repository (e.g. https://github.com/solven-eu/cleanthat/blob/master/.cleanthat/cleanthat.yaml).

It differs from mvn/gradle integration by fetching only relevant (e.g. modified) files, based on Github Events.

• https://docs.github.com/en/developers/webhooks-and-events/events/github-event-types#pullrequestevent
• https://docs.github.com/en/developers/webhooks-and-events/events/github-event-types#pushevent

• Automatic generation of the initial configuration
• Clean branches which are not protected and head of a PullRequest

• Cleanthat itself
• Pepper

If you integrated Cleanthat through its maven or gradle options, you can get automatic remote cleaning with:

    ./mvnw spotless:check || ./mvnw spotless:apply && git commit -m"Spotless" && git push

As of 2022-12, this projects focuses on typical JVM projects. Hence, it enables:

• Advanced Linting of .java files
• Advanced Formatting of .java files (through Spotless)
• Advanced Formatting of pom.xml files (through Spotless)
• Basic Formatting of .json, .xml, etc files (through Spotless)

One major goal of this project is to enable incremental refactoring on a per Pull-Request basis. Hence, the availability of the whole code-base and related binaries (e.g. mvn dependencies) is limited. Cleanthat focuses on cleaning individual source files.

Limitations :

• Can not refactor based on multiple source files information (e.g. type definition in a different file)
• Can not refactor based on binaries information (e.g. type definition from dependencies)
• Can refactor based on standard JRE classpath

While we work on integrating CleanThat into Spotless, the Github CleanThat App does not rely on existing Maven (https://github.com/diffplug/spotless/tree/main/plugin-maven) and Gradle (https://github.com/diffplug/spotless/tree/main/plugin-gradle) plugins. The main reason for that is security. Indeed, while it would enable very setup over a project already integrating Spotless, it would open dangerous security breach as one could easily inject custom code as dependency of the maven/gradle plugin, which would enable one to extract CleanThat secrets (Github token, GPG key, etc).

Refactoring .java files would break the code conventions. Hence, any refactoring operation should be followed by a formatting operation. With mvn integration, once should follow the cleanthat step with some mvn formatter step. With github integration, once may rely on CleanThat own .java formatting abilities.

There is multiple good options for formatting Java files:

• https://github.com/revelc/formatter-maven-plugin
• https://github.com/diffplug/spotless/blob/main/plugin-maven/README.md (e.g. https://github.com/JnRouvignac/AutoRefactor/blob/master/pom.xml#L240)

This software is provided WITHOUT ANY WARRANTY, and is available under the Apache License, Version 2. Any code loss caused by using this plugin is not the responsibility of the author(s). Be sure to use some source repository management system such as GIT before using this plugin.

Contributions are welcome.

An alternative to spring_formatter is eclipse_formatter. It takes as parameter an url like:

A public http(s) URL:

    https://raw.githubusercontent.com/solven-eu/pepper/master/static/src/main/resources/eclipse/eclipse_java_code_formatter.xml

A file in local repository (root being assumed based on Git root/Maven top module)

    code:/static/src/main/resources/eclipse/eclipse_java_code_formatter.xml

Eclipse Stylesheets can exported to XML through:

• Go into Preferences
• Select Java > Code Style > Formatter
• Click on 'Export All'

CleanThat will accept only configuration with a single profile in them. If multiple profiles are found, we will rely on the first profile.

The maven plugin enables generating an Eclipse Stylesheet minimizing changes over a clean repository:

    mvn io.github.solven-eu.cleanthat:cleanthat-maven-plugin:eclipse_formatter-stylesheet

see maven/README.MD

cleanthat is fairly new. While it is tested on many large projects, you may encounter issues of all kinds. Please report them.