Maracas

Maracas is a source code and bytecode analysis framework⁠—written in Java with the help of Spoon—designed to analyze how Java libraries evolve and how their evolution impact their clients.

Currently, Maracas consists of two main components:

The core API computes the list of changes between two binary versions of a library (using japicmp under the hood) and the impact these changes have on client code
The REST API exposes a set of REST endpoints that make it easy to ask Maracas to analyze library versions and clients. In particular, it is used by break-bot to analyze pull requests on GitHub and report their impact

Using Maracas

Dependency

maracas-core is deployed on GitHub Packages. First, configure Maven or Gradle to work with GitHub Package. Then, declare the following dependency:

<dependency>
  <groupId>com.github.maracas</groupId>
  <artifactId>maracas-core</artifactId>
  <version>0.0.1-SNAPSHOT</version>
</dependency>

As an API

One may use Maracas to compute the changes between two versions of a library as well as their impact on a particular client as follows.

Note that both versions of the library must be provided as binary JARs, while the client is provided as source code.

Path v1 = Paths.get("v1.jar");
Path v2 = Paths.get("v2.jar");
Path c =  Paths.get("/path/to/client/src/main/java");

// Using a query/result
AnalysisQuery query = AnalysisQuery.builder()
  .oldJar(v1)
  .newJar(v2)
  .client(c)
  .build();

AnalysisResult result = Maracas.analyze(query);
Delta delta = result.delta();
Set<BrokenUse> brokenUses = result.allBrokenUses();

// Programmatically
Delta delta = Maracas.computeDelta(v1, v2);
Set<BreakingChange> breakingChanges = delta.getBreakingChanges();

DeltaImpact deltaImpact = Maracas.computeDeltaImpact(c, delta);
Set<BrokenUse> brokenUses = deltaImpact.getBrokenUses();

// Delta models are built from JARs and lack source code locations.
// To map breaking changes to precise locations in source code,
// feed the delta with the library's source code:
delta.populateLocations(Paths.get("/path/to/v1/src/main/java"));

From the command line

Alternatively, one can invoke Maracas from the command line using the provided CLI. First, build a standalone JAR from Maracas Core, and then follow the --help guidelines:

$ cd core/
$ mvn clean compile assembly:single
$ java -jar target/maracas-core-<version>-jar-with-dependencies.jar --help

The example above can be invoked from the CLI as follows:

$ java -jar target/maracas-core-<version>-jar-with-dependencies.jar --old v1.jar --new v2.jar --client /path/to/client/src/main/java

Deploying Maracas REST

Configuration

As Maracas REST needs to interact with the GitHub REST API, one must first configure a personal token to be used. To do so, a file named .github must be placed in the rest/src/main/resources/ directory with the following content:

$ cat rest/src/main/resources/.github
oauth=<GITHUB_TOKEN>

Execution

The preferred way to run the Maracas REST server is using Docker:

$ cd rest/
$ docker-compose up

The REST server listens on port 8080. Its documentation is exposed at http://localhost:8080/swagger-ui/index.html?configUrl=/api-docs/swagger-config.

Documentation

To learn more about Maracas and how to use it, please visit our GitHub page.

Support

If you would like to learn more about Maracas or you are a current user and you need some help, do not hesitate to send us an email at thomas.degueule <at> labri.fr or l.m.ochoa.venegas <at> tue.nl.

Contributing

To learn more about how to contribute to Maracas, please check the provided guidelines and the project code of conduct.

jrfaller / maracas