fix: join the build lifecycle with dependsOn, not finalizedBy (#89)

Since 0.1.2 a consumer that declares its own
`build.dependsOn(assembleRequirements)` fails at configuration time:

    Circular dependency between the following tasks:
    :assembleRequirements
    \--- :build
         \--- :assembleRequirements (*)

Nothing compiles -- the build dies before any task runs.

0.1.2 added `build.finalizedBy(assembleRequirements)`, which says the task
runs AFTER build. The consumer's line says before. Gradle rejects the
contradiction. Consumers had every reason to have written that line:
0.1.0 and 0.1.1 shipped no lifecycle wiring at all, while the 0.1.0
README documented the task as depending on `check` and running as part of
`build`. They wired by hand to get the documented behaviour, and 0.1.2
added the opposing edge with no migration note.

Wiring `build dependsOn assembleRequirements dependsOn check` instead
keeps the same execution order -- the task still runs after the tests
whose XML it reads -- while composing with those consumers rather than
contradicting them. dependsOn is idempotent, so their line is now
redundant and harmless, and no consumer has to edit its build file.

It also makes `gradle assembleRequirements` on its own meaningful: it now
runs `check` first, so the zip contains test results instead of silently
omitting them.

Covered by BuildLifecycleWiringTest, which drives a real consumer project
through TestKit with `--dry-run` -- a circular dependency is raised while
the task graph is built, so the regression is reproduced without
compiling or resolving anything. Verified to fail against the old wiring
before being made to pass. tests/fixtures/test_project cannot cover this:
it declares no wiring of its own, so it only ever exercises the case
where the plugin is the sole author of these edges.

Closes #88

Signed-off-by: Jimisola Laursen <jimisola@jimisola.com>

Author: jimisola

CLAUDE.md

@@ -26,6 +26,7 @@ src/main/java/io/github/reqstool/gradle/
 
 src/test/java/io/github/reqstool/gradle/
   RequirementsToolTaskTest.java   # unit tests (see below)
+  BuildLifecycleWiringTest.java   # TestKit: how the task joins `build` (issue #88)
 
 src/test/resources/{yml,zip}/     # tracked reference fixtures (see "Fixtures" below)
 
@@ -35,8 +36,13 @@ docs/modules/ROOT/                # Antora documentation source (published to re
 ```
 
 The main task is `assembleRequirements` (group `build`). When the `java` plugin is applied,
-the plugin auto-wires it to depend on `compileJava` and every non-main source set's compile
-task, and makes `build` finalized by `assembleRequirements`.
+the plugin auto-wires it to depend on `check`, on `compileJava` and on every non-main source
+set's compile task, and makes `build` depend on `assembleRequirements`.
+
+Use `dependsOn` rather than `finalizedBy` for that last edge. `dependsOn` is idempotent, so
+a consumer that wired the lifecycle by hand — as 0.1.0 and 0.1.1 required — merely repeats
+an edge that already exists. `finalizedBy` states the opposite order and Gradle rejects the
+pair as a circular dependency at configuration time; that was issue #88.
 
 ## Running tests
 
@@ -61,6 +67,21 @@ Jackson (`ObjectMapper` + `YAMLFactory`) — it does **not** read from `src/test
 | `testDeprecatedSvcsAnnotationsFileSetter` | The deprecated singular `setSvcsAnnotationsFile()` still works and delegates to `svcsAnnotationsFiles` |
 | `testMissingRequirementsFile` | `task.execute()` throws an exception whose message mentions `requirements.yml` when the dataset directory doesn't contain it |
 
+## Lifecycle tests — `BuildLifecycleWiringTest`
+
+TestKit (`GradleRunner`) over a throwaway consumer project, run with `--dry-run`: a circular
+dependency is raised while Gradle builds the task graph, so the failure is reproduced
+without compiling or resolving anything.
+
+| Test | Validates |
+|---|---|
+| `consumerDeclaringBuildDependsOnAssembleRequirementsStillConfigures` | A consumer's own `build.dependsOn(assembleRequirements)` does not collide with the plugin's wiring — the regression in #88 |
+| `assembleRequirementsIsPartOfBuildWithoutConsumerWiring` | The plugin alone still puts the task into `build` |
+| `assembleRequirementsRunsAfterCheck` | `check` is ordered first, since the task reads test-result XML |
+
+`tests/fixtures/test_project` cannot cover this: it declares no wiring of its own, so it only
+ever exercises the case where the plugin is the sole author of these edges.
+
 ## Fixtures
 
 ### `src/test/resources/{yml,zip}/`

README.md

@@ -12,7 +12,7 @@ Gradle build plugin for [reqstool](https://github.com/reqstool/reqstool-client)
 
 Collects `@Requirements` and `@SVCs` annotations from compiled Java code, combines them with test results, and packages everything into a ZIP artifact for analysis by the reqstool CLI. Supports Java 21+.
 
-The plugin automatically wires task dependencies: `assembleRequirements` depends on all `compileJava` tasks, and `build` is finalized by `assembleRequirements`. No manual task wiring is needed in most projects.
+The plugin automatically wires task dependencies: `assembleRequirements` depends on `check` and on all `compileJava` tasks, and `build` depends on `assembleRequirements`. No manual task wiring is needed in most projects.
 
 ## Installation
 
@@ -109,7 +109,8 @@ Combines requirements and SVCs annotations from all source sets, writes a merged
 
 - Depends on `compileJava` (main source set)
 - Depends on `compileXxxJava` for each non-main source set (unless `svcsAnnotationsFiles` was set explicitly)
-- `build` is finalized by `assembleRequirements`
+- `assembleRequirements` depends on `check`
+- `build` depends on `assembleRequirements`
 
 ## Usage
 

build.gradle

@@ -50,6 +50,10 @@ dependencies {
     testImplementation 'io.github.reqstool:reqstool-java-annotations:1.0.1'
     testAnnotationProcessor 'io.github.reqstool:reqstool-java-annotations:1.0.1'
 
+    // TestKit runs a real Gradle build, which is the only way to observe a
+    // configuration-time circular dependency (see BuildLifecycleWiringTest).
+    testImplementation gradleTestKit()
+
     // Testing - JUnit BOM for version management
     testImplementation platform('org.junit:junit-bom:6.1.3')
     testImplementation 'org.junit.jupiter:junit-jupiter-api'

docs/modules/ROOT/pages/configuration.adoc

@@ -166,9 +166,12 @@ When the `java` plugin is applied, the plugin automatically wires:
 
 * `assembleRequirements` depends on `compileJava` (main source set)
 * `assembleRequirements` depends on `compileXxxJava` for each non-main source set (unless `svcsAnnotationsFiles` was set explicitly via `setSvcsAnnotationsFiles(...)`)
-* `build` is finalized by `assembleRequirements`
+* `assembleRequirements` depends on `check`, so test results exist when it runs
+* `build` depends on `assembleRequirements`
 
-No manual `dependsOn` or `finalizedBy` blocks are needed in the consuming project.
+No manual `dependsOn` blocks are needed in the consuming project. If you already have
+`build.dependsOn(assembleRequirements)` from an earlier version, it is now redundant but
+harmless -- `dependsOn` is idempotent.
 
 If an annotation file is missing at execution time (e.g. when a compile task was excluded), the plugin emits a `WARN` message identifying the missing file.
 

docs/modules/ROOT/pages/index.adoc

@@ -5,7 +5,7 @@ This Gradle plugin generates a ZIP artifact containing combined annotations and
 == Features
 
 * *Zero-configuration*: Works out of the box with sensible defaults
-* *Automatic task wiring*: `assembleRequirements` depends on all compile tasks; `build` is finalized by `assembleRequirements`
+* *Automatic task wiring*: `assembleRequirements` depends on `check` and all compile tasks; `build` depends on `assembleRequirements`
 * *Multi-source-set support*: SVCs annotation files are auto-discovered from all non-main source sets
 * *Maven publishing support*: Automatically registers ZIP artifact for publication
 * *Combines annotations*: Merges requirements annotations from implementation and test code

docs/modules/ROOT/pages/usage.adoc

@@ -67,7 +67,8 @@ then (unless `skipAssembleZipArtifact` is set) assembles a ZIP artifact at
 
 * Depends on `compileJava` (main source set — generates `requirementsAnnotationsFile`)
 * Depends on `compileXxxJava` for each non-main source set (generates entries in `svcsAnnotationsFiles`)
-* `build` is finalized by `assembleRequirements`
+* Depends on `check`, so the test results it reads have been produced
+* `build` depends on `assembleRequirements`
 
 These dependencies ensure annotation processors run before the task executes.
 No manual wiring is needed unless you override annotation file paths with `setSvcsAnnotationsFiles(...)`.
@@ -77,10 +78,11 @@ No manual wiring is needed unless you override annotation file paths with `setSv
 [source]
 ----
 build
- └── (finalizedBy) assembleRequirements
-                    ├── (dependsOn) compileJava
-                    ├── (dependsOn) compileTestJava
-                    └── (dependsOn) compileIntegrationTestJava  (if source set exists)
+ └── (dependsOn) assembleRequirements
+                  ├── (dependsOn) check
+                  ├── (dependsOn) compileJava
+                  ├── (dependsOn) compileTestJava
+                  └── (dependsOn) compileIntegrationTestJava  (if source set exists)
 ----
 
 ZIP artifact is written to `build/reqstool/<name>-<version>-reqstool.zip`.

src/main/java/io/github/reqstool/gradle/RequirementsToolPlugin.java

@@ -3,6 +3,7 @@
 
 import org.gradle.api.Plugin;
 import org.gradle.api.Project;
+import org.gradle.api.plugins.JavaBasePlugin;
 import org.gradle.api.plugins.JavaPlugin;
 import org.gradle.api.plugins.JavaPluginExtension;
 import org.gradle.api.publish.PublishingExtension;
@@ -81,7 +82,19 @@ public void apply(Project project) {
 						.forEach(ss -> assembleTask
 							.configure(task -> task.dependsOn(project.getTasks().named(ss.getCompileJavaTaskName()))));
 				}
-				project.getTasks().named("build").configure(build -> build.finalizedBy(assembleTask));
+				// `build dependsOn assembleRequirements dependsOn check`, not
+				// `build finalizedBy assembleRequirements`. Both put the task after the
+				// tests, which it needs -- it reads their XML output -- but only this
+				// one composes with a consumer that already wired the lifecycle by
+				// hand. dependsOn is idempotent, so a consumer repeating either edge
+				// changes nothing; finalizedBy contradicts a consumer's
+				// `build.dependsOn(assembleRequirements)` and Gradle rejects the pair
+				// as a circular dependency at configuration time, failing the build
+				// before anything compiles. Versions 0.1.0 and 0.1.1 wired nothing at
+				// all, so consumers had every reason to write that line themselves.
+				// See reqstool/reqstool-java-gradle-plugin#88.
+				assembleTask.configure(task -> task.dependsOn(p.getTasks().named(JavaBasePlugin.CHECK_TASK_NAME)));
+				p.getTasks().named("build").configure(build -> build.dependsOn(assembleTask));
 			});
 		});
 

src/test/java/io/github/reqstool/gradle/BuildLifecycleWiringTest.java

@@ -0,0 +1,101 @@
+// Copyright © LFV
+package io.github.reqstool.gradle;
+
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+
+import org.gradle.testkit.runner.BuildResult;
+import org.gradle.testkit.runner.GradleRunner;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/**
+ * Covers how the plugin joins the build lifecycle, which the fixture under
+ * {@code tests/fixtures} cannot: the fixture declares no wiring of its own, so it only
+ * ever exercises the case where the plugin is the sole author of these edges.
+ *
+ * <p>
+ * {@code --dry-run} is deliberate. A circular dependency is raised while Gradle builds
+ * the task graph, before any task runs, so the failure these tests guard against is
+ * reproduced without compiling anything or resolving a single dependency.
+ *
+ * @see <a href= "https://github.com/reqstool/reqstool-java-gradle-plugin/issues/88">issue
+ * #88</a>
+ */
+class BuildLifecycleWiringTest {
+
+	@TempDir
+	Path projectDir;
+
+	/**
+	 * Versions 0.1.0 and 0.1.1 wired nothing, so a consumer that wanted the documented
+	 * behaviour declared it by hand. That line must not collide with the plugin's own
+	 * wiring: 0.1.2 made {@code build} finalized by {@code assembleRequirements}, which
+	 * contradicts it, and every such consumer failed at configuration time with "Circular
+	 * dependency between the following tasks".
+	 */
+	@Test
+	void consumerDeclaringBuildDependsOnAssembleRequirementsStillConfigures() throws IOException {
+		writeProject("""
+				tasks.named('assembleRequirements') { dependsOn(tasks.named('check')) }
+				tasks.named('build') { dependsOn(tasks.named('assembleRequirements')) }
+				""");
+
+		BuildResult result = run();
+
+		assertFalse(result.getOutput().contains("Circular dependency"),
+				"consumer-declared build.dependsOn(assembleRequirements) must not collide "
+						+ "with the plugin's own wiring:\n" + result.getOutput());
+		assertTrue(result.getOutput().contains(":assembleRequirements"),
+				"assembleRequirements should be in the task graph for `build`:\n" + result.getOutput());
+	}
+
+	/** The plugin on its own still puts the task into {@code build}. */
+	@Test
+	void assembleRequirementsIsPartOfBuildWithoutConsumerWiring() throws IOException {
+		writeProject("");
+
+		BuildResult result = run();
+
+		assertTrue(result.getOutput().contains(":assembleRequirements"),
+				"assembleRequirements should run as part of `build`:\n" + result.getOutput());
+	}
+
+	/**
+	 * The task reads the test-results XML, so it has to come after the tests rather than
+	 * merely alongside them.
+	 */
+	@Test
+	void assembleRequirementsRunsAfterCheck() throws IOException {
+		writeProject("");
+
+		String output = run().getOutput();
+
+		assertTrue(output.indexOf(":check") < output.indexOf(":assembleRequirements"),
+				"check should be ordered before assembleRequirements:\n" + output);
+	}
+
+	private BuildResult run() {
+		return GradleRunner.create()
+			.withProjectDir(projectDir.toFile())
+			.withPluginClasspath()
+			.withArguments("build", "--dry-run")
+			.build();
+	}
+
+	private void writeProject(String extraWiring) throws IOException {
+		Files.writeString(projectDir.resolve("settings.gradle"), "rootProject.name = 'consumer'\n");
+		Files.writeString(projectDir.resolve("build.gradle"), """
+				plugins {
+				    id 'java'
+				    id 'io.github.reqstool.gradle-plugin'
+				}
+
+				""" + extraWiring);
+	}
+
+}