{"id":48313118,"url":"https://github.com/alien-tools/maracas","last_synced_at":"2026-04-05T00:25:21.354Z","repository":{"id":40350092,"uuid":"376718714","full_name":"alien-tools/maracas","owner":"alien-tools","description":"Maracas is a source code and bytecode analysis framework⁠—written in Java with the help of Spoon—which analyzes how Java libraries evolve and how their evolution impacts their clients.","archived":false,"fork":false,"pushed_at":"2025-02-15T22:29:40.000Z","size":28828,"stargazers_count":16,"open_issues_count":16,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-01-28T00:39:57.822Z","etag":null,"topics":["api","breaking-changes","java"],"latest_commit_sha":null,"homepage":"https://alien-tools.github.io/maracas/","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alien-tools.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2021-06-14T06:01:02.000Z","updated_at":"2025-07-14T07:16:57.000Z","dependencies_parsed_at":"2025-02-15T23:33:13.697Z","dependency_job_id":null,"html_url":"https://github.com/alien-tools/maracas","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/alien-tools/maracas","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alien-tools%2Fmaracas","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alien-tools%2Fmaracas/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alien-tools%2Fmaracas/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alien-tools%2Fmaracas/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alien-tools","download_url":"https://codeload.github.com/alien-tools/maracas/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alien-tools%2Fmaracas/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31419699,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-05T00:25:07.052Z","status":"ssl_error","status_checked_at":"2026-04-05T00:25:05.923Z","response_time":60,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","breaking-changes","java"],"created_at":"2026-04-05T00:25:21.269Z","updated_at":"2026-04-05T00:25:21.335Z","avatar_url":"https://github.com/alien-tools.png","language":"Java","readme":"![Build \u0026 Test](https://github.com/alien-tools/maracas/actions/workflows/build.yml/badge.svg?branch=main) ![CodeQL](https://github.com/alien-tools/maracas/actions/workflows/codeql-analysis.yml/badge.svg?branch=main) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n**_You might want to check out [Roseau](https://github.com/alien-tools/roseau) for our latest work on breaking changes!_**\n\n# Maracas\n\nMaracas is a source code and bytecode analysis framework—written in Java with the help of [Spoon](https://github.com/INRIA/Spoon)—that tracks how Java libraries evolve and how their evolution impacts their clients. In a nutshell, Maracas makes it easy to:\n\n  - Track the introduction of backward-incompatible breaking changes in your own APIs or the APIs you rely on\n  - Analyze the concrete impact of these breaking changes on the client code using these APIs\n  - Analyze local Java artifacts (source code and JARs) or analyze commits, branches, and pull requests remotely hosted on software forges such as GitHub. if you'd like to automatically check your pull requests for the introduction of breaking changes and their impact, you should give a try to our GitHub App [BreakBot](https://github.com/alien-tools/breakbot) :robot:!\n\nMaracas consists of three main components:\n\n  - The [core API](core/) identifies breaking changes between two binary versions of a library (using [japicmp](https://github.com/siom79/japicmp) under the hood) and the impact these changes have on client code\n  - The [forges API](forges/) handles communication with software forges (currently GitHub only) and build systems (currently Maven and Gradle) to gather source code and build JARs that are then analyzed by the core API\n  - The [REST API](rest/) makes it easy to ask Maracas to analyze library versions and clients. In particular, it is used by [BreakBot](https://github.com/alien-tools/breakbot) to analyze pull requests on GitHub.\n\n## Content\n\n- [Using Maracas](#using-maracas)\n- [Deploying Maracas REST](#deploying-maracas-rest)\n- [Documentation](#documentation)\n- [Support](#support)\n- [License](#license)\n\n\n## Using Maracas\n\n### Dependency\n\n`maracas-core` is deployed on GitHub Packages.\nFirst, configure [Maven](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-apache-maven-registry) or [Gradle](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-gradle-registry) to work with GitHub Package.\nThen, include the following dependency:\n\n```xml\n\u003cdependency\u003e\n  \u003cgroupId\u003ecom.github.maracas\u003c/groupId\u003e\n  \u003cartifactId\u003emaracas-core\u003c/artifactId\u003e\n  \u003cversion\u003e0.5.0\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n### Analyzing local libraries and clients\nOne can use Maracas to compute the changes between two versions of a library as well as their impact on a particular client as follows.\n\n*Note that both versions of the library must be provided as binary JARs, while the client is provided as source code.*\n\n```java\nMaracas maracas = new Maracas();\n\n// Setting up the library versions and clients\nLibraryJar v1 = LibraryJar.withSources(Path.of(\"v1.jar\"), Path.of(\"v1-sources/\"));\nLibraryJar v2 = LibraryJar.withoutSources(Path.of(\"v2.jar\"));\nSourcesDirectory client = SourcesDirectory.of(Path.of(\"/path/to/client\"));\n\n// Option 1: using the query/result API\nAnalysisQuery query = AnalysisQuery.builder()\n  .of(v1, v2)\n  .client(client)\n  .build();\n\nAnalysisResult result = maracas.analyze(query);\nDelta delta = result.delta();\nList\u003cBreakingChange\u003e breakingChanges = delta.getBreakingChanges();\nSet\u003cBrokenUse\u003e brokenUses = result.allBrokenUses();\n\n// Option 2: invoking the analyses directly\nDelta delta = maracas.computeDelta(v1, v2);\nCollection\u003cBreakingChange\u003e breakingChanges = delta.getBreakingChanges();\n\nDeltaImpact deltaImpact = maracas.computeDeltaImpact(client, delta);\nSet\u003cBrokenUse\u003e brokenUses = deltaImpact.brokenUses();\n```\n\n### Analyzing GitHub repositories\n\nAlternatively, one can use the [forges API](forges/) to analyze artifacts hosted on GitHub.\n\n```java\n// See https://github-api.kohsuke.org/ to setup the GitHubBuilder\nGitHubForge forge = new GitHubForge(GitHubBuilder.fromEnvironment().build());\n\n// Option 1: analyzing a pull request\nPullRequestAnalyzer analyzer = new PullRequestAnalyzer(forge);\nPullRequest pr = forge.fetchPullRequest(\"owner\", \"library\", 42);\n\nPullRequestAnalysisResult result = analyzer.analyze(pr, MaracasOptions.newDefault());\nList\u003cBreakingChange\u003e breakingChanges = result.breakingChanges();\nSet\u003cBrokenUse\u003e brokenUses = result.brokenUses();\n\n// Option 2: analyzing two arbitrary commits\nCommitAnalyzer analyzer = new CommitAnalyzer();\nCommit v1 = forge.fetchCommit(\"owner\", \"library\", \"sha-v1\");\nCommit v2 = forge.fetchCommit(\"owner\", \"library\", \"sha-v2\");\nCommit client = forge.fetchCommit(\"owner\", \"client\", \"sha-client\");\n\nAnalysisResult result = analyzer.analyzeCommits(new CommitBuilder(v1), new CommitBuilder(v2),\n    List.of(new CommitBuilder(client)), MaracasOptions.newDefault());\n\nList\u003cBreakingChange\u003e breakingChanges = result.delta().getBreakingChanges();\nSet\u003cBrokenUse\u003e brokenUses = result.allBrokenUses();\n```\n\n### From the command line\nAlternatively, one can invoke Maracas from the command line using the provided CLI.\nFirst, build a standalone JAR from Maracas Core, and then follow the `--help` guidelines:\n\n```bash\n$ cd core/\n$ mvn clean compile assembly:single\n$ java -jar target/maracas-core-\u003cversion\u003e-jar-with-dependencies.jar --help\n```\n\nThe example above can be invoked from the CLI as follows:\n\n```bash\n$ java -jar target/maracas-core-\u003cversion\u003e-jar-with-dependencies.jar --old v1.jar --new v2.jar --client /path/to/client/src/main/java\n```\n\n## Deploying Maracas REST\n\n### Configuration\nAs Maracas REST needs to interact with the GitHub REST API, one must first configure a [personal token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) to be used.\nTo do so, a file named `.github` must be placed in the `rest/src/main/resources/` directory with the following content:\n\n```bash\n$ cat rest/src/main/resources/.github\noauth=\u003cGITHUB_TOKEN\u003e\n```\n\n### Execution\nThe preferred way to run the Maracas REST server is using Docker:\n```bash\n$ cd rest/\n$ docker-compose build\n$ docker-compose up\n```\n\nThe REST server listens on port `8080`. Its documentation is exposed at `http://localhost:8080/swagger-ui.html`.\n\n\n## Documentation\nTo learn more about Maracas, please visit our [GitHub page](https://alien-tools.github.io/maracas/).\n\n\n## Support\nIf you would like to learn more about Maracas or you are a current user and you need some help, do not hesitate to ask questions in issues or to get in touch with [Lina Ochoa](https://github.com/lmove) or [Thomas Degueule](https://github.com/tdegueul).\n\n## License\nThis repository—and all its content—is licensed under the [MIT License](https://choosealicense.com/licenses/mit/).  \n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falien-tools%2Fmaracas","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falien-tools%2Fmaracas","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falien-tools%2Fmaracas/lists"}