Release 0.5.0

README.md

@@ -35,45 +35,73 @@ Then, include the following dependency:
 <dependency>
   <groupId>com.github.maracas</groupId>
   <artifactId>maracas-core</artifactId>
-  <version>0.4.0</version>
+  <version>0.5.0</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.
+### Analyzing local libraries and clients
+One can 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.*
 
 ```java
+Maracas maracas = new Maracas();
+
 // Setting up the library versions and clients
-LibraryJar v1 = new LibraryJar(Path.of("v1.jar"));
-LibraryJar v2 = new LibraryJar(Path.of("v2.jar"));
-SourcesDirectory client = new SourcesDirectory(Path.of("/path/to/client"));
+LibraryJar v1 = LibraryJar.withSources(Path.of("v1.jar"), Path.of("v1-sources/"));
+LibraryJar v2 = LibraryJar.withoutSources(Path.of("v2.jar"));
+SourcesDirectory client = SourcesDirectory.of(Path.of("/path/to/client"));
 
-// Using a query/result
+// Option 1: using the query/result API
 AnalysisQuery query = AnalysisQuery.builder()
   .oldVersion(v1)
   .newVersion(v2)
   .client(client)
   .build();
 
-AnalysisResult result = Maracas.analyze(query);
+AnalysisResult result = maracas.analyze(query);
 Delta delta = result.delta();
 List<BreakingChange> breakingChanges = delta.getBreakingChanges();
 Set<BrokenUse> brokenUses = result.allBrokenUses();
 
-// Or by directly invoking the analysis methods
-Delta delta = Maracas.computeDelta(v1, v2);
+// Option 2: invoking the analyses directly
+Delta delta = maracas.computeDelta(v1, v2);
 Collection<BreakingChange> breakingChanges = delta.getBreakingChanges();
 
-DeltaImpact deltaImpact = Maracas.computeDeltaImpact(client, delta);
-Set<BrokenUse> brokenUses = deltaImpact.getBrokenUses();
+DeltaImpact deltaImpact = maracas.computeDeltaImpact(client, delta);
+Set<BrokenUse> brokenUses = deltaImpact.brokenUses();
+```
+
+### Analyzing GitHub repositories
 
-// Delta models are built from JARs and lack source code locations.
-// To map breaking changes to precise locations in source code,
-// create a library jar with its corresponding source code
-LibraryJar v1 = new LibraryJar(Path.of("v1.jar"),
-	new SourcesDirectory(Path.of("/path/to/v1/src")));
+Alternatively, one can use the [forges API](forges/) to analyze artifacts hosted on GitHub.
+
+```java
+// See https://github-api.kohsuke.org/ to setup the GitHubBuilder
+GitHubForge forge = new GitHubForge(GitHubBuilder.fromEnvironment().build());
+
+// Option 1: analyzing a pull request
+PullRequestAnalyzer analyzer = new PullRequestAnalyzer(Path.of("/tmp"), forge);
+PullRequest pr = forge.fetchPullRequest("owner", "library", 42);
+
+PullRequestAnalysisResult result = analyzer.analyze(pr, MaracasOptions.newDefault());
+List<BreakingChange> breakingChanges = result.breakingChanges();
+Set<BrokenUse> brokenUses = result.brokenUses();
+
+// Option 2: analyzing two arbitrary commits
+CommitAnalyzer analyzer = new CommitAnalyzer();
+Commit v1 = forge.fetchCommit("owner", "library", "sha-v1");
+Commit v2 = forge.fetchCommit("owner", "library", "sha-v2");
+Commit client = forge.fetchCommit("owner", "client", "sha");
+CommitBuilder builderV1 = new CommitBuilder(v1, Path.of("clone-v1/"));
+CommitBuilder builderV2 = new CommitBuilder(v2, Path.of("clone-v2/"));
+CommitBuilder builderClient = new CommitBuilder(client, Path.of("clone-client/"));
+
+AnalysisResult result = analyzer.analyzeCommits(builderV1, builderV2,
+  List.of(builderClient), MaracasOptions.newDefault());
+
+List<BreakingChange> breakingChanges = result.delta().getBreakingChanges();
+Set<BrokenUse> brokenUses = result.allBrokenUses();
 ```
 
 ### From the command line

core/pom.xml

@@ -6,7 +6,7 @@
 	<parent>
 		<groupId>com.github.maracas</groupId>
 		<artifactId>maracas-parent</artifactId>
-		<version>0.5.0-SNAPSHOT</version>
+		<version>0.5.0</version>
 	</parent>
 
 	<artifactId>maracas-core</artifactId>

core/src/main/java/com/github/maracas/LibraryJar.java

@@ -66,6 +66,10 @@ public static LibraryJar withSources(Path jar, SourcesDirectory sources) {
 		return new LibraryJar(jar, sources);
 	}
 
+	public static LibraryJar withSources(Path jar, Path sources) {
+		return new LibraryJar(jar, SourcesDirectory.of(sources));
+	}
+
 	public static LibraryJar withoutSources(Path jar) {
 		return new LibraryJar(jar, null);
 	}

core/src/main/java/com/github/maracas/Usage.java

@@ -0,0 +1,69 @@
+package com.github.maracas;
+
+import com.github.maracas.brokenuse.BrokenUse;
+import com.github.maracas.brokenuse.DeltaImpact;
+import com.github.maracas.delta.BreakingChange;
+import com.github.maracas.delta.Delta;
+
+import java.nio.file.Path;
+import java.util.Collection;
+import java.util.List;
+import java.util.Set;
+
+@SuppressWarnings("unused")
+class Usage {
+	public static void main(String[] args) {
+		LibraryJar v1 = LibraryJar.withSources(
+			Path.of("test-data/comp-changes/old/target/comp-changes-old-0.0.1.jar"),
+			SourcesDirectory.of(Path.of("test-data/comp-changes/old/")));
+		LibraryJar v2 = LibraryJar.withoutSources(Path.of("test-data/comp-changes/new/target/comp-changes-new-0.0.1.jar"));
+		SourcesDirectory client = SourcesDirectory.of(Path.of("test-data/comp-changes/client/"));
+
+		AnalysisQuery query = AnalysisQuery.builder()
+			.oldVersion(v1)
+			.newVersion(v2)
+			.client(client)
+			.build();
+
+		AnalysisResult result = new Maracas().analyze(query);
+		System.out.println("Changes: " + result.delta());
+		System.out.println("Impact:  " + result.allBrokenUses());
+	}
+
+	void readmeUsage1() {
+		Maracas maracas = new Maracas();
+
+		// Setting up the library versions and clients
+		LibraryJar v1 = LibraryJar.withSources(Path.of("v1.jar"), Path.of("v1-sources/"));
+		LibraryJar v2 = LibraryJar.withoutSources(Path.of("v2.jar"));
+		SourcesDirectory client = SourcesDirectory.of(Path.of("/path/to/client"));
+
+		// Option 1: using the query/result API
+		AnalysisQuery query = AnalysisQuery.builder()
+			.oldVersion(v1)
+			.newVersion(v2)
+			.client(client)
+			.build();
+
+		AnalysisResult result = maracas.analyze(query);
+		Delta delta = result.delta();
+		List<BreakingChange> breakingChanges = delta.getBreakingChanges();
+		Set<BrokenUse> brokenUses = result.allBrokenUses();
+	}
+
+	void readmeUsage2() {
+		Maracas maracas = new Maracas();
+
+		// Setting up the library versions and clients
+		LibraryJar v1 = LibraryJar.withSources(Path.of("v1.jar"), Path.of("v1-sources/"));
+		LibraryJar v2 = LibraryJar.withoutSources(Path.of("v2.jar"));
+		SourcesDirectory client = SourcesDirectory.of(Path.of("/path/to/client"));
+
+		// Option 2: invoking the analyses directly
+		Delta delta = maracas.computeDelta(v1, v2);
+		Collection<BreakingChange> breakingChanges = delta.getBreakingChanges();
+
+		DeltaImpact deltaImpact = maracas.computeDeltaImpact(client, delta);
+		Set<BrokenUse> brokenUses = deltaImpact.brokenUses();
+	}
+}

core/src/test/java/com/github/maracas/TestData.java

@@ -1,7 +1,6 @@
 package com.github.maracas;
 
 import java.nio.file.Path;
-import java.nio.file.Paths;
 
 public class TestData {
 	public static Path validJar = Path.of("../test-data/comp-changes/old/target/comp-changes-old-0.0.1.jar");

experiments/pom.xml

@@ -6,7 +6,7 @@
 	<parent>
 		<groupId>com.github.maracas</groupId>
 		<artifactId>maracas-parent</artifactId>
-		<version>0.5.0-SNAPSHOT</version>
+		<version>0.5.0</version>
 	</parent>
 
 	<artifactId>maracas-experiments</artifactId>

forges/pom.xml

@@ -6,7 +6,7 @@
 	<parent>
 		<groupId>com.github.maracas</groupId>
 		<artifactId>maracas-parent</artifactId>
-		<version>0.5.0-SNAPSHOT</version>
+		<version>0.5.0</version>
 	</parent>
 
 	<artifactId>maracas-forges</artifactId>

forges/src/main/java/com/github/maracas/forges/Usage.java

@@ -0,0 +1,53 @@
+package com.github.maracas.forges;
+
+import com.github.maracas.AnalysisResult;
+import com.github.maracas.MaracasOptions;
+import com.github.maracas.brokenuse.BrokenUse;
+import com.github.maracas.delta.BreakingChange;
+import com.github.maracas.forges.analysis.CommitAnalyzer;
+import com.github.maracas.forges.analysis.PullRequestAnalysisResult;
+import com.github.maracas.forges.analysis.PullRequestAnalyzer;
+import com.github.maracas.forges.build.CommitBuilder;
+import com.github.maracas.forges.github.GitHubForge;
+import org.kohsuke.github.GitHubBuilder;
+
+import java.io.IOException;
+import java.nio.file.Path;
+import java.util.List;
+import java.util.Set;
+
+@SuppressWarnings("unused")
+class Usage {
+	void readmeUsage1() throws IOException {
+		// See https://github-api.kohsuke.org/ to setup the GitHubBuilder
+		GitHubForge forge = new GitHubForge(GitHubBuilder.fromEnvironment().build());
+
+		// Option 1: analyzing a pull request
+		PullRequestAnalyzer analyzer = new PullRequestAnalyzer(Path.of("/tmp"), forge);
+		PullRequest pr = forge.fetchPullRequest("owner", "library", 42);
+
+		PullRequestAnalysisResult result = analyzer.analyze(pr, MaracasOptions.newDefault());
+		List<BreakingChange> breakingChanges = result.breakingChanges();
+		Set<BrokenUse> brokenUses = result.brokenUses();
+	}
+
+	void readmeUsage2() throws IOException {
+		// See https://github-api.kohsuke.org/ to setup the GitHubBuilder
+		GitHubForge forge = new GitHubForge(GitHubBuilder.fromEnvironment().build());
+
+		// Option 2: analyzing two arbitrary commits
+		CommitAnalyzer analyzer = new CommitAnalyzer();
+		Commit v1 = forge.fetchCommit("owner", "library", "sha-v1");
+		Commit v2 = forge.fetchCommit("owner", "library", "sha-v2");
+		Commit client = forge.fetchCommit("owner", "client", "sha");
+		CommitBuilder builderV1 = new CommitBuilder(v1, Path.of("clone-v1/"));
+		CommitBuilder builderV2 = new CommitBuilder(v2, Path.of("clone-v2/"));
+		CommitBuilder builderClient = new CommitBuilder(client, Path.of("clone-client/"));
+
+		AnalysisResult result = analyzer.analyzeCommits(builderV1, builderV2,
+			List.of(builderClient), MaracasOptions.newDefault());
+
+		List<BreakingChange> breakingChanges = result.delta().getBreakingChanges();
+		Set<BrokenUse> brokenUses = result.allBrokenUses();
+	}
+}

forges/src/main/java/com/github/maracas/forges/analysis/CommitAnalyzer.java

@@ -40,6 +40,10 @@ public CommitAnalyzer(Maracas maracas) {
 		this(maracas, Executors.newFixedThreadPool(Runtime.getRuntime().availableProcessors()));
 	}
 
+	public CommitAnalyzer() {
+		this(new Maracas());
+	}
+
 	public AnalysisResult analyzeCommits(CommitBuilder v1, CommitBuilder v2, Collection<CommitBuilder> clients, MaracasOptions options)
 		throws CloneException, BuildException {
 		Objects.requireNonNull(v1);

forges/src/main/java/com/github/maracas/forges/analysis/PullRequestAnalysisResult.java

@@ -1,10 +1,16 @@
 package com.github.maracas.forges.analysis;
 
+import com.github.maracas.brokenuse.BrokenUse;
+import com.github.maracas.delta.BreakingChange;
 import com.github.maracas.forges.PullRequest;
 
 import java.nio.file.Path;
+import java.util.Collection;
+import java.util.List;
 import java.util.Map;
 import java.util.Objects;
+import java.util.Set;
+import java.util.stream.Collectors;
 
 public record PullRequestAnalysisResult(
     PullRequest pr,
@@ -16,4 +22,18 @@ public record PullRequestAnalysisResult(
     Objects.requireNonNull(packageResults);
     Objects.requireNonNull(basePath);
   }
+
+  public List<BreakingChange> breakingChanges() {
+    return packageResults().values().stream()
+      .map(pkg -> pkg.delta().getBreakingChanges())
+      .flatMap(Collection::stream)
+      .toList();
+  }
+
+  public Set<BrokenUse> brokenUses() {
+    return packageResults().values().stream()
+      .map(PackageAnalysisResult::allBrokenUses)
+      .flatMap(Collection::stream)
+      .collect(Collectors.toSet());
+  }
 }

forges/src/main/java/com/github/maracas/forges/analysis/PullRequestAnalyzer.java

@@ -47,6 +47,10 @@ public PullRequestAnalyzer(Path workingDirectory, Forge forge, CommitAnalyzer co
 		this(workingDirectory, forge, commitAnalyzer, Executors.newFixedThreadPool(Runtime.getRuntime().availableProcessors()));
 	}
 
+	public PullRequestAnalyzer(Path workingDirectory, Forge forge) {
+		this(workingDirectory, forge, new CommitAnalyzer());
+	}
+
 	public PullRequestAnalysisResult analyze(PullRequest pr, MaracasOptions options) {
 		Objects.requireNonNull(pr);
 		Objects.requireNonNull(options);

pom.xml

@@ -27,7 +27,7 @@
 	<groupId>com.github.maracas</groupId>
 	<artifactId>maracas-parent</artifactId>
 	<packaging>pom</packaging>
-	<version>0.5.0-SNAPSHOT</version>
+	<version>0.5.0</version>
 	<name>Maracas parent module</name>
 
 	<modules>

rest/pom.xml

@@ -7,7 +7,7 @@
 	<parent>
 		<groupId>com.github.maracas</groupId>
 		<artifactId>maracas-parent</artifactId>
-		<version>0.5.0-SNAPSHOT</version>
+		<version>0.5.0</version>
 	</parent>
 
 	<artifactId>maracas-rest</artifactId>

test-data/api-evolution-data-corpus/client/pom.xml

@@ -5,7 +5,7 @@
   <parent>
     <groupId>com.github.maracas</groupId>
     <artifactId>api-evolution-data-corpus-parent</artifactId>
-    <version>0.5.0-SNAPSHOT</version>
+    <version>0.5.0</version>
   </parent>
   <artifactId>api-evolution-data-corpus-client</artifactId>
   <version>0.0.1</version>

test-data/api-evolution-data-corpus/lib-v1/pom.xml

@@ -6,7 +6,7 @@
 	<parent>
 		<groupId>com.github.maracas</groupId>
 		<artifactId>api-evolution-data-corpus-parent</artifactId>
-		<version>0.5.0-SNAPSHOT</version>
+		<version>0.5.0</version>
 	</parent>
 
 	<artifactId>api-evolution-data-corpus-lib-v1</artifactId>

test-data/api-evolution-data-corpus/lib-v2/pom.xml

@@ -6,7 +6,7 @@
 	<parent>
 		<groupId>com.github.maracas</groupId>
 		<artifactId>api-evolution-data-corpus-parent</artifactId>
-		<version>0.5.0-SNAPSHOT</version>
+		<version>0.5.0</version>
 	</parent>
 
 	<artifactId>api-evolution-data-corpus-lib-v2</artifactId>