Skip to content

Latest commit

 

History

History
178 lines (121 loc) · 8.06 KB

README.md

File metadata and controls

178 lines (121 loc) · 8.06 KB
Raw

Sorald GHA tests Workflow Status Code Coverage Supported Platforms

Sorald is a tool to automatically repair violations of static analysis rules checked with SonarQube. It can currently repair violations of 25+ rules based on the design described in Sorald: Automatic Patch Suggestions for SonarQube Static Analysis Violations (doi:10.1109/TDSC.2022.3167316).

If you use Sorald in an academic context, please copy BibTeX or APA citation from the citation widget on the sidebar of main page.

Talks

Getting started

Prerequisites

Sorald supports macOS, Linux, and Windows.

For running Sorald, all you need is a Java 11+ runtime.

For building Sorald from source, you need a Java 11+ JDK, Maven >=3.6.3, and Git.

Running Sorald in 2 seconds

Sorald is available as a maven-plugin so you can run it from the command line with Maven.

mvn se.kth.castor:sorald:repair -DruleKey=<ruleKey>

Note: Sorald maven-plugin is still in rudimentary stages. We have added two goals to it - mine and repair. They both are analogous to the CLI tool. However, not all parameters are supported yet. We are working on adding more.

Use describe goal of maven-help-plugin to see the list of parameters supported by the plugin. Example:

mvn help:describe -Dplugin=se.kth.castor:sorald -Ddetail

For example, the following commands repair violations of S1132 in SonarSource/sonar-scanner-cli@5c518d6.

# Cloning and moving into the project
git clone [email protected]:SonarSource/sonar-scanner-cli.git
cd sonar-scanner-cli/
git checkout 5c518d6a

# Running Sorald
mvn se.kth.castor:sorald:repair -DruleKey=S1132

# Checking the result
git diff

You may also see the demo video:

sorald-demo.mp4

Getting a Sorald JAR

To run Sorald, you need to first get your hands on the program. You can do this either by building from source, or going to the latest release and downloading the file called sorald-<VERSION>-jar-with-dependencies.jar listed under Assets. Unless you keep multiple versions of Sorald, we recommend renaming the JAR to sorald.jar for the sake of simplicity.

Build

  1. Clone this repository: git clone https://github.com/SpoonLabs/sorald.git

  2. Build:

$ cd sorald
$ mvn package -DskipTests
$ cp sorald/target/sorald-*-jar-with-dependencies.jar sorald.jar

The Sorald application can now be found in sorald.jar in the current working directory.

Usage

Sorald can perform two different tasks: automatically repair violations of Sonar rules in a project, or mine projects for rule violations. These two modes of operations are available as the two commands repair and mine, respectively.

For the remainder of this section, assume that we have defined the following alias:

alias sorald='java -jar /abs/path/to/sorald.jar'

If you don't like using aliases, simply substitute in java -jar sorald.jar for any occurrence of sorald in these instructions.

Repairing rule violations (the repair command)

To repair rule violations, use the repair command.

$ sorald repair <arguments ...>

Basic usage consists of specifying a project to target and a rule to repair violations of. The available rules can be found here, and are specified by their key. For example, to repair violations of the rule 2111: "BigDecimal(double)" should not be used in a project at some/project/path, one can invoke Sorald like so.

$ sorald repair --source some/project/path --rule-key 2111

The full list of options is documented here (and can also be found by running sorald repair --help):

Mining Sonar warnings (the mine command)

To mine projects for Sonar warnings, use the mine command. Its most basic usage consists of simply pointing it to a project directory.

$ sorald mine --source path/to/project

It will then output statistics for that project with the Sonar checks available in Sorald.

Another option is to execute the miner on a list of remote Git repositories, which can be done like so.

$ sorald mine --stats-on-git-repos --git-repos-list repos.txt --stats-output-file output.txt --temp-dir /tmp

The --gitReposList should be a plain text file with one remote repository url (e.g. https://github.com/SpoonLabs/sorald.git) per line. Sorald clones each repository and runs Sonar checks on the head of the default branch.

The full list of options documented here (and can also be found by running sorald mine --help).

Running Sorald on GitHub projects to propose PRs with fixes

To run Sorald on projects towards proposing fixes in the form of PRs, look at this Git repository for an example. In it, Sorald is ran on the three Apache projects defined in the projects_for_model_1.txt file.

Releases

Our releases are signed using travis-gumtree-spoon's GPG key. The key is hosted here. You may run the following commands to verify the signature of a release.

gpg --recv-keys 1429025e3eda19a5
gpg --verify sorald-<VERSION>-jar-with-dependencies.jar.asc

This signature is a type of detaached signature, so you need to have the JAR file as well to verify the signature.

Academic bibliographic references

"Sorald: Automatic Patch Suggestions for SonarQube Static Analysis Violations" (Khashayar Etemadi, Nicolas Harrand, Simon Larsen, Haris Adzemovic, Henry Luong Phu, Ashutosh Verma, Fernanda Madeiral, Douglas Wikstrom and Martin Monperrus), Technical report, arXiv 2103.12033, 2021.

"A template-based approach to automatic program repair of Sonarqube static warnings", by Haris Adzemovic, Master's thesis, KTH, School of Electrical Engineering and Computer Science (EECS), 2020. (bibtex)

Experiments with Sorald

Sorald-Experiments repository includes the data related to our experiments with Sorald that are part of a recently conducted research project.

Sorald downloads sonar-java-plugin.jar at runtime. See config file for its URL. Although most of the time it automatically downloads and loads it, you can manually download and store it if needed. See

sorald/sorald/src/main/java/sorald/FileUtils.java

Line 127 in 02c0721

public static File getCacheDir() {
for the name of the directory for different filesystems. The file is called sonar-java-plugin.jar. In linux, ~/.cache/sorald/sonar-java-plugin.jar is the path of the downloaded jar.

Contributing

Contributions are welcome! Feel free to open issues on this GitHub repository, and also to open pull requests for making this project nicer (see instructions here).