Skip to content

Commit 555ea77

Browse files
committed
Add deterministic Maven and Gradle bridges (#63)
1 parent 9de96a4 commit 555ea77

12 files changed

Lines changed: 524 additions & 0 deletions

File tree

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Gradle integration contract
2+
3+
Wrap `GradleBuildIntegration.check(...)` in a cacheable `check`-lifecycle task whose declared task
4+
dependencies are `classes` and, when analyzed, `testClasses`. An empty output directory fails with a
5+
clear ordering-specific message.
6+
7+
Pass the project root, the reviewed ArchUnitJava configuration, and source-set output directories
8+
directly. The bridge sorts and validates those directories, requires an exact match with the
9+
configuration's `inputs`, and then calls the shared CLI/library contract. It never starts Gradle,
10+
runs a nested build, loads project classes, or executes project plugins or annotation processors.
11+
12+
Treat all supplied paths and formats as task inputs. Result-format overrides map one-to-one to
13+
`CliResultFormat`; graph-format overrides are accepted only for graph operations. Preserve the CLI
14+
exit-code distinction between policy failures (`5`) and incomplete analysis (`4`).

‎build-integrations/maven/README.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Maven integration contract
2+
3+
Bind a thin Mojo around `MavenBuildIntegration.verify(...)` to Maven's `verify` phase. The goal
4+
must run after every relevant module has completed `compile` or `test-compile`; an empty output
5+
directory fails with an ordering-specific message.
6+
7+
Pass the reactor root, the reviewed ArchUnitJava configuration, and every compiled output directory
8+
directly. The bridge sorts and validates those directories, requires an exact match with the
9+
configuration's `inputs`, and then calls the shared CLI/library contract. It never starts Maven,
10+
invokes another lifecycle, loads project classes, or runs project plugins or annotation processors.
11+
12+
Map a check result to the documented CLI exit codes. In particular, code `5` means architecture
13+
policy failure, while code `4` means incomplete analysis. Result-format overrides map one-to-one to
14+
`CliResultFormat`; graph-format overrides are accepted only for graph operations.
Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
package dev.archunitjava.integration;
2+
3+
/** Shared CLI operation exposed through build tools. */
4+
public enum BuildCommand {
5+
CHECK("check"),
6+
GRAPH("graph");
7+
8+
private final String cliName;
9+
10+
BuildCommand(String cliName) {
11+
this.cliName = cliName;
12+
}
13+
14+
String cliName() {
15+
return cliName;
16+
}
17+
}
Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
package dev.archunitjava.integration;
2+
3+
/** Clear configuration or lifecycle failure reported to the hosting build tool. */
4+
public final class BuildIntegrationException extends RuntimeException {
5+
public BuildIntegrationException(String message) {
6+
super(message);
7+
}
8+
9+
public BuildIntegrationException(String message, Throwable cause) {
10+
super(message, cause);
11+
}
12+
}
Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
package dev.archunitjava.integration;
2+
3+
import dev.archunitjava.cli.CliGraphFormat;
4+
import dev.archunitjava.cli.CliResultFormat;
5+
import java.nio.file.Path;
6+
import java.util.List;
7+
import java.util.Objects;
8+
import java.util.Optional;
9+
10+
/** Lossless mapping from build-tool inputs to the shared CLI/library contract. */
11+
public record BuildIntegrationRequest(
12+
BuildTool tool,
13+
String lifecycle,
14+
Path approvedRoot,
15+
Path configuration,
16+
List<Path> compiledOutputs,
17+
BuildCommand command,
18+
Optional<CliResultFormat> resultFormat,
19+
Optional<CliGraphFormat> graphFormat) {
20+
public BuildIntegrationRequest {
21+
Objects.requireNonNull(tool, "tool");
22+
if (lifecycle == null || lifecycle.isBlank()) {
23+
throw new IllegalArgumentException("lifecycle must not be blank");
24+
}
25+
Objects.requireNonNull(approvedRoot, "approvedRoot");
26+
Objects.requireNonNull(configuration, "configuration");
27+
Objects.requireNonNull(compiledOutputs, "compiledOutputs");
28+
compiledOutputs = List.copyOf(compiledOutputs);
29+
if (compiledOutputs.isEmpty() || compiledOutputs.size() > 256) {
30+
throw new BuildIntegrationException(
31+
"Build integration requires between 1 and 256 compiled outputs");
32+
}
33+
compiledOutputs.forEach(output -> Objects.requireNonNull(output, "compiledOutput"));
34+
Objects.requireNonNull(command, "command");
35+
Objects.requireNonNull(resultFormat, "resultFormat");
36+
Objects.requireNonNull(graphFormat, "graphFormat");
37+
if (command == BuildCommand.CHECK && graphFormat.isPresent()) {
38+
throw new BuildIntegrationException("A check command cannot override graph format");
39+
}
40+
if (command == BuildCommand.GRAPH && resultFormat.isPresent()) {
41+
throw new BuildIntegrationException("A graph command cannot override result format");
42+
}
43+
}
44+
}
Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
package dev.archunitjava.integration;
2+
3+
import java.nio.file.Path;
4+
import java.util.List;
5+
import java.util.Objects;
6+
7+
/** Build-host result retaining the deterministic compiled-output order. */
8+
public record BuildIntegrationResult(
9+
BuildTool tool, String lifecycle, int exitCode, List<Path> compiledOutputs) {
10+
public BuildIntegrationResult {
11+
Objects.requireNonNull(tool, "tool");
12+
Objects.requireNonNull(lifecycle, "lifecycle");
13+
compiledOutputs = List.copyOf(Objects.requireNonNull(compiledOutputs, "compiledOutputs"));
14+
}
15+
}
Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
package dev.archunitjava.integration;
2+
3+
import dev.archunitjava.cli.CliConfiguration;
4+
import dev.archunitjava.cli.CliConfigurationLoader;
5+
import dev.archunitjava.cli.CliGraphFormat;
6+
import dev.archunitjava.cli.CliResultFormat;
7+
import dev.archunitjava.cli.CliRunner;
8+
import java.io.IOException;
9+
import java.nio.file.Files;
10+
import java.nio.file.LinkOption;
11+
import java.nio.file.Path;
12+
import java.util.ArrayList;
13+
import java.util.List;
14+
import java.util.Objects;
15+
import java.util.TreeSet;
16+
17+
/**
18+
* Executes the shared contract against already-compiled outputs.
19+
*
20+
* <p>This class has no process-launching API and never invokes Maven, Gradle, compilers, target
21+
* classes, plugins, or annotation processors.
22+
*/
23+
public final class BuildIntegrationRunner {
24+
public BuildIntegrationResult run(
25+
BuildIntegrationRequest request, Appendable standardOut, Appendable standardError) {
26+
BuildIntegrationRequest value = Objects.requireNonNull(request, "request");
27+
try {
28+
Path root = value.approvedRoot().toRealPath();
29+
if (!Files.isDirectory(root, LinkOption.NOFOLLOW_LINKS)) {
30+
throw new BuildIntegrationException("Approved build root must be a directory");
31+
}
32+
List<Path> outputs = outputs(root, value.compiledOutputs(), value.tool());
33+
CliConfiguration configuration = CliConfigurationLoader.load(
34+
value.configuration(), root);
35+
if (!configuration.inputs().equals(outputs)) {
36+
throw new BuildIntegrationException(
37+
"Compiled outputs do not exactly match the validated CLI inputs");
38+
}
39+
List<String> arguments = new ArrayList<>(List.of(
40+
value.command().cliName(),
41+
"--config", configuration.source().toString(),
42+
"--root", root.toString()));
43+
value.resultFormat().ifPresent(format -> {
44+
arguments.add("--result-format");
45+
arguments.add(resultFormat(format));
46+
});
47+
value.graphFormat().ifPresent(format -> {
48+
arguments.add("--graph-format");
49+
arguments.add(format.name().toLowerCase(java.util.Locale.ROOT));
50+
});
51+
int exit = new CliRunner().run(
52+
arguments.toArray(String[]::new), standardOut, standardError);
53+
return new BuildIntegrationResult(value.tool(), value.lifecycle(), exit, outputs);
54+
} catch (BuildIntegrationException error) {
55+
throw error;
56+
} catch (IOException | RuntimeException error) {
57+
throw new BuildIntegrationException(
58+
value.tool() + " integration could not validate compiled outputs: "
59+
+ safeMessage(error), error);
60+
}
61+
}
62+
63+
private static List<Path> outputs(
64+
Path root, List<Path> configured, BuildTool tool) throws IOException {
65+
TreeSet<Path> sorted = new TreeSet<>();
66+
for (Path output : configured) {
67+
Path candidate = (output.isAbsolute() ? output : root.resolve(output)).normalize();
68+
if (!candidate.startsWith(root)) {
69+
throw new BuildIntegrationException("Compiled output escapes the approved root");
70+
}
71+
Path resolved = candidate.toRealPath();
72+
if (!resolved.startsWith(root) || !Files.isDirectory(resolved, LinkOption.NOFOLLOW_LINKS)) {
73+
throw new BuildIntegrationException(
74+
"Compiled output must be a directory inside the approved root: " + output);
75+
}
76+
if (!containsClass(resolved)) {
77+
String ordering = tool == BuildTool.MAVEN
78+
? "Bind the architecture check to verify after compile/test-compile."
79+
: "Make the architecture check task depend on classes/testClasses.";
80+
throw new BuildIntegrationException(
81+
"Compiled output contains no .class files: " + output + ". " + ordering);
82+
}
83+
if (!sorted.add(resolved)) {
84+
throw new BuildIntegrationException(
85+
"Compiled outputs resolve to the same directory more than once: " + output);
86+
}
87+
}
88+
return List.copyOf(sorted);
89+
}
90+
91+
private static boolean containsClass(Path directory) throws IOException {
92+
try (var paths = Files.walk(directory)) {
93+
return paths.limit(100_001)
94+
.anyMatch(path -> Files.isRegularFile(path, LinkOption.NOFOLLOW_LINKS)
95+
&& path.getFileName().toString().endsWith(".class"));
96+
}
97+
}
98+
99+
private static String resultFormat(CliResultFormat format) {
100+
return format == CliResultFormat.JUNIT_XML
101+
? "junit-xml" : format.name().toLowerCase(java.util.Locale.ROOT);
102+
}
103+
104+
private static String safeMessage(Exception error) {
105+
String message = error.getMessage();
106+
return (message == null || message.isBlank() ? error.getClass().getSimpleName() : message)
107+
.replace("\r", "\\r").replace("\n", "\\n");
108+
}
109+
}
Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
package dev.archunitjava.integration;
2+
3+
/** Supported build hosts for the first-party integration bridge. */
4+
public enum BuildTool {
5+
MAVEN,
6+
GRADLE
7+
}
Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
package dev.archunitjava.integration;
2+
3+
import dev.archunitjava.cli.CliGraphFormat;
4+
import dev.archunitjava.cli.CliResultFormat;
5+
import java.nio.file.Path;
6+
import java.util.Collection;
7+
import java.util.List;
8+
import java.util.Optional;
9+
10+
/** Gradle-facing entry point intended for a check task after classes/testClasses. */
11+
public final class GradleBuildIntegration {
12+
public BuildIntegrationResult check(
13+
Path projectRoot,
14+
Path configuration,
15+
Collection<Path> sourceSetOutputDirectories,
16+
BuildCommand command,
17+
Optional<CliResultFormat> resultFormat,
18+
Optional<CliGraphFormat> graphFormat,
19+
Appendable standardOut,
20+
Appendable standardError) {
21+
return new BuildIntegrationRunner().run(new BuildIntegrationRequest(
22+
BuildTool.GRADLE,
23+
"check",
24+
projectRoot,
25+
configuration,
26+
List.copyOf(sourceSetOutputDirectories),
27+
command,
28+
resultFormat,
29+
graphFormat), standardOut, standardError);
30+
}
31+
}
Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
package dev.archunitjava.integration;
2+
3+
import dev.archunitjava.cli.CliGraphFormat;
4+
import dev.archunitjava.cli.CliResultFormat;
5+
import java.nio.file.Path;
6+
import java.util.Collection;
7+
import java.util.List;
8+
import java.util.Optional;
9+
10+
/** Maven-facing entry point intended for the verify phase after all module outputs exist. */
11+
public final class MavenBuildIntegration {
12+
public BuildIntegrationResult verify(
13+
Path reactorRoot,
14+
Path configuration,
15+
Collection<Path> moduleOutputDirectories,
16+
BuildCommand command,
17+
Optional<CliResultFormat> resultFormat,
18+
Optional<CliGraphFormat> graphFormat,
19+
Appendable standardOut,
20+
Appendable standardError) {
21+
return new BuildIntegrationRunner().run(new BuildIntegrationRequest(
22+
BuildTool.MAVEN,
23+
"verify",
24+
reactorRoot,
25+
configuration,
26+
List.copyOf(moduleOutputDirectories),
27+
command,
28+
resultFormat,
29+
graphFormat), standardOut, standardError);
30+
}
31+
}

0 commit comments

Comments
 (0)