Skip to content

Commit 336eb88

Browse files
jimisolajimisola
authored
fix: restore deprecated svcsAnnotationsFile setter and auto-wire task dependencies (#53)
* fix: restore deprecated svcsAnnotationsFile setter for backwards compatibility Adds a deprecated setSvcsAnnotationsFile(Object) setter to RequirementsToolExtension that delegates to svcsAnnotationsFiles.from() and emits a WARN-level deprecation message. This restores compatibility for builds using the 0.1.0 property name after upgrading to 0.1.1+. Closes #52 Signed-off-by: Jimisola Laursen <jimisola@jimisola.com> * feat: auto-wire task dependencies and warn on missing annotation files - Auto-wire assembleRequirements to depend on compileJava (main) and all non-main compileXxxJava tasks via JavaPlugin introspection in afterEvaluate - Wire build.finalizedBy(assembleRequirements) so no manual lifecycle configuration is needed in consuming projects - Add setSvcsAnnotationsFiles(Object...) setter that marks files as explicit and disables auto-wired test source set compile dependencies - Emit WARN when annotation files are missing at execution time - Remove manual dependsOn/finalizedBy from fixture build.gradle - Add complete configuration reference table and task documentation to README Closes #54 Signed-off-by: Jimisola Laursen <jimisola@jimisola.com> * docs: update Antora docs to reflect auto-wiring and svcsAnnotationsFiles changes - Rewrite configuration.adoc with a reference table, dataset directory table, auto-wiring explanation, setSvcsAnnotationsFiles override docs, and deprecation notice for svcsAnnotationsFile (singular) - Update usage.adoc with correct task lifecycle (compile deps, not check), lifecycle diagram, and task reference - Update index.adoc to reflect auto-wiring feature and correct defaults Signed-off-by: Jimisola Laursen <jimisola@jimisola.com> * fix: resolve Spring format violation and add missing javadoc @PARAM tag - Apply Spring java format to RequirementsToolExtension - Add missing @PARAM tag to setSvcsAnnotationsFile javadoc - Add svcsAnnotationsFile (deprecated) row to README configuration table - Remove redundant Deprecation notice section from README Signed-off-by: Jimisola Laursen <jimisola@jimisola.com> --------- Signed-off-by: Jimisola Laursen <jimisola@jimisola.com>
1 parent 859b2f2 commit 336eb88

9 files changed

Lines changed: 316 additions & 147 deletions

File tree

‎README.md‎

Lines changed: 55 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -12,28 +12,77 @@ Gradle build plugin for [reqstool](https://github.com/reqstool/reqstool-client)
1212

1313
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+.
1414

15+
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.
16+
1517
## Installation
1618

1719
Add the plugin to your `build.gradle`:
1820

1921
```groovy
2022
plugins {
21-
id 'io.github.reqstool.gradle-plugin' version '0.1.0'
23+
id 'io.github.reqstool.gradle-plugin' version '0.1.1'
2224
}
2325
2426
requirementsTool {
2527
datasetPath = file('docs/reqstool')
2628
}
29+
```
2730

28-
tasks.named('build') {
29-
finalizedBy tasks.named('assembleRequirements')
30-
}
31+
The `assembleRequirements` task runs automatically as part of `build`. No additional wiring is required.
32+
33+
## Configuration
34+
35+
All properties are optional. Defaults match the standard Gradle project layout.
36+
37+
| Property | Type | Default | Description |
38+
|---|---|---|---|
39+
| `requirementsAnnotationsFile` | `RegularFileProperty` | `build/generated/sources/annotationProcessor/java/main/resources/annotations.yml` | Requirements annotations YAML file generated by the annotation processor for the main source set |
40+
| `svcsAnnotationsFiles` | `ConfigurableFileCollection` | Auto-discovered from all non-main source sets | SVCs annotations YAML files, one per test source set (e.g. `test`, `integrationTest`) |
41+
| `svcsAnnotationsFile` _(deprecated)_ | `Object` | — | **Deprecated since 0.1.1.** Use `svcsAnnotationsFiles.from(...)` instead. Delegates to `svcsAnnotationsFiles` and emits a `WARN` log. |
42+
| `outputDirectory` | `RegularFileProperty` | `build/reqstool` | Output directory for the ZIP artifact and combined annotations file |
43+
| `datasetPath` | `RegularFileProperty` | `reqstool/` (project directory) | Directory containing `requirements.yml` and optional supporting files |
44+
| `testResults` | `ListProperty<String>` | `["build/test-results/**/*.xml"]` | Ant-style glob patterns for test result XML files to include in the ZIP |
45+
| `skip` | `Property<Boolean>` | `false` | Skip all plugin execution |
46+
| `skipAssembleZipArtifact` | `Property<Boolean>` | `false` | Skip ZIP assembly; annotations are still combined into `annotations.yml` |
47+
| `skipAttachZipArtifact` | `Property<Boolean>` | `false` | Skip attaching the ZIP artifact to Maven publications |
48+
49+
### Dataset directory
50+
51+
The `datasetPath` directory must contain at minimum a `requirements.yml` file. Optional files in the same directory are included if present:
52+
53+
| File | Required |
54+
|---|---|
55+
| `requirements.yml` | Yes |
56+
| `software_verification_cases.yml` | No |
57+
| `manual_verification_results.yml` | No |
58+
59+
### Overriding auto-discovered annotation files
3160

32-
tasks.named('assembleRequirements') {
33-
dependsOn tasks.named('test')
61+
To replace the auto-discovered SVCs annotation files with explicit paths (also disables auto-wired compile dependencies for test source sets):
62+
63+
```groovy
64+
requirementsTool {
65+
setSvcsAnnotationsFiles(
66+
file('custom/path/test-annotations.yml'),
67+
file('custom/path/it-annotations.yml')
68+
)
3469
}
3570
```
3671

72+
## Task reference
73+
74+
### `assembleRequirements`
75+
76+
Group: `build`
77+
78+
Combines requirements and SVCs annotations from all source sets, writes a merged `annotations.yml` to `outputDirectory`, and (unless `skipAssembleZipArtifact` is set) assembles a ZIP artifact at `<outputDirectory>/<name>-<version>-reqstool.zip`.
79+
80+
**Auto-wired dependencies** (when the `java` plugin is applied):
81+
82+
- Depends on `compileJava` (main source set)
83+
- Depends on `compileXxxJava` for each non-main source set (unless `svcsAnnotationsFiles` was set explicitly)
84+
- `build` is finalized by `assembleRequirements`
85+
3786
## Usage
3887

3988
```bash

‎docs/modules/ROOT/pages/configuration.adoc‎

Lines changed: 100 additions & 92 deletions
Original file line numberDiff line numberDiff line change
@@ -1,146 +1,154 @@
1-
== Configuration
1+
= Configuration
22

3-
The plugin provides zero-configuration defaults, but you can customize if needed:
3+
The plugin provides zero-configuration defaults that match the standard Gradle project layout.
4+
Override only what you need.
45

5-
=== Complete Configuration Example
6+
== Configuration reference
67

7-
[source,gradle]
8-
----
9-
requirementsTool {
10-
// Path to requirements annotations YAML
11-
// Default: build/generated-sources/annotations/resources/annotations.yml
12-
requirementsAnnotationsFile = file('build/custom-path/annotations.yml')
8+
[cols="1,1,2,2",options="header"]
9+
|===
10+
|Property |Type |Default |Description
1311

14-
// Path to SVCS annotations YAML
15-
// Default: build/generated-test-sources/test-annotations/resources/annotations.yml
16-
svcsAnnotationsFile = file('build/custom-path/test-annotations.yml')
12+
|`requirementsAnnotationsFile`
13+
|`RegularFileProperty`
14+
|`build/generated/sources/annotationProcessor/java/main/resources/annotations.yml`
15+
|Requirements annotations YAML file generated by the annotation processor for the main source set
1716

18-
// Output directory for ZIP and combined annotations
19-
// Default: build/reqstool
20-
outputDirectory = file('build/custom-output')
17+
|`svcsAnnotationsFiles`
18+
|`ConfigurableFileCollection`
19+
|Auto-discovered from all non-main source sets
20+
|SVCs annotations YAML files, one per test source set (e.g. `test`, `integrationTest`)
2121

22-
// Dataset directory containing requirements.yml and optional files
23-
// Default: ./reqstool
24-
datasetPath = file('custom-reqstool-data')
22+
|`svcsAnnotationsFile` _(deprecated)_
23+
|`Object`
24+
|—
25+
|*Deprecated since 0.1.1.* Use `svcsAnnotationsFiles.from(...)` instead. Delegates to `svcsAnnotationsFiles` and emits a `WARN` log.
2526

26-
// Test result file patterns
27-
// Default: ['build/test-results/**/*.xml']
28-
testResults = ['build/test-results/**/*.xml', 'build/custom-tests/**/*.xml']
27+
|`outputDirectory`
28+
|`RegularFileProperty`
29+
|`build/reqstool`
30+
|Output directory for the ZIP artifact and combined `annotations.yml`
2931

30-
// Skip entire plugin execution
31-
// Default: false
32-
skip = false
32+
|`datasetPath`
33+
|`RegularFileProperty`
34+
|`reqstool/` (project directory)
35+
|Directory containing `requirements.yml` and optional supporting files
3336

34-
// Skip ZIP assembly but keep annotation combining
35-
// Default: false
36-
skipAssembleZipArtifact = false
37+
|`testResults`
38+
|`ListProperty<String>`
39+
|`["build/test-results/**/*.xml"]`
40+
|Ant-style glob patterns for test result XML files to include in the ZIP
3741

38-
// Skip artifact attachment for publishing
39-
// Default: false
40-
skipAttachZipArtifact = false
41-
}
42-
----
42+
|`skip`
43+
|`Property<Boolean>`
44+
|`false`
45+
|Skip all plugin execution
4346

44-
=== Configuration Parameters
47+
|`skipAssembleZipArtifact`
48+
|`Property<Boolean>`
49+
|`false`
50+
|Skip ZIP assembly; annotations are still combined into `annotations.yml`
4551

46-
==== requirementsAnnotationsFile
52+
|`skipAttachZipArtifact`
53+
|`Property<Boolean>`
54+
|`false`
55+
|Skip attaching the ZIP artifact to Maven publications
56+
|===
4757

48-
The `requirementsAnnotationsFile` parameter specifies the path to the requirements annotations file.
49-
Defaults to the value set below.
58+
== Dataset directory
5059

51-
[source,gradle]
52-
----
53-
requirementsTool {
54-
requirementsAnnotationsFile = file('build/generated-sources/annotations/resources/annotations.yml')
55-
}
56-
----
60+
The `datasetPath` directory must contain at minimum a `requirements.yml` file.
61+
Optional files in the same directory are included if present.
5762

58-
==== svcsAnnotationsFile
63+
[cols="1,1",options="header"]
64+
|===
65+
|File |Required
5966

60-
The `svcsAnnotationsFile` parameter specifies the path to the SVCS (Software Verification Cases) annotations file.
61-
Defaults to the value set below.
67+
|`requirements.yml`
68+
|Yes
6269

63-
[source,gradle]
64-
----
65-
requirementsTool {
66-
svcsAnnotationsFile = file('build/generated-test-sources/test-annotations/resources/annotations.yml')
67-
}
68-
----
70+
|`software_verification_cases.yml`
71+
|No
72+
73+
|`manual_verification_results.yml`
74+
|No
75+
|===
6976

70-
==== outputDirectory
77+
== Minimal configuration
7178

72-
The `outputDirectory` parameter specifies the path to where to put the generated output.
73-
Defaults to the value set below.
79+
Only `datasetPath` needs to be set when the dataset lives outside the default `reqstool/` directory:
7480

7581
[source,gradle]
7682
----
7783
requirementsTool {
78-
outputDirectory = file('build/reqstool')
84+
datasetPath = file('docs/reqstool')
7985
}
8086
----
8187

82-
==== datasetPath
83-
84-
The `datasetPath` parameter specifies the path to the dataset directory containing requirements.yml and optional files.
85-
Defaults to the value set below.
88+
== Complete configuration example
8689

8790
[source,gradle]
8891
----
8992
requirementsTool {
90-
datasetPath = file('./reqstool')
93+
requirementsAnnotationsFile =
94+
file('build/generated/sources/annotationProcessor/java/main/resources/annotations.yml')
95+
96+
// svcsAnnotationsFiles is a file collection — use .from() to add files additively
97+
svcsAnnotationsFiles.from(
98+
file('build/generated/sources/annotationProcessor/java/test/resources/annotations.yml')
99+
)
100+
101+
outputDirectory = file('build/reqstool')
102+
datasetPath = file('docs/reqstool')
103+
testResults = ['build/test-results/**/*.xml']
104+
skip = false
105+
skipAssembleZipArtifact = false
106+
skipAttachZipArtifact = false
91107
}
92108
----
93109

94-
==== testResults
110+
== Overriding auto-discovered annotation files
95111

96-
The `testResults` parameter specifies one or more test result file patterns.
97-
Supports Ant-style pattern matching.
112+
`svcsAnnotationsFiles` is auto-discovered from all non-main source sets.
113+
To replace auto-discovery with explicit paths (also disables auto-wired compile dependencies for test source sets):
98114

99115
[source,gradle]
100116
----
101117
requirementsTool {
102-
testResults = ['build/test-results/**/*.xml', 'build/custom-tests/**/*.xml']
118+
setSvcsAnnotationsFiles(
119+
file('custom/path/test-annotations.yml'),
120+
file('custom/path/it-annotations.yml')
121+
)
103122
}
104123
----
105124

106-
==== skip
125+
== Auto-wired task dependencies
107126

108-
Skip the execution of the entire plugin.
109-
Defaults to the value set below.
127+
When the `java` plugin is applied, the plugin automatically wires:
110128

111-
[source,gradle]
112-
----
113-
requirementsTool {
114-
skip = false
115-
}
116-
----
129+
* `assembleRequirements` depends on `compileJava` (main source set)
130+
* `assembleRequirements` depends on `compileXxxJava` for each non-main source set (unless `svcsAnnotationsFiles` was set explicitly via `setSvcsAnnotationsFiles(...)`)
131+
* `build` is finalized by `assembleRequirements`
132+
133+
No manual `dependsOn` or `finalizedBy` blocks are needed in the consuming project.
134+
135+
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.
117136

118-
==== skipAssembleZipArtifact
137+
== Deprecation notice
119138

120-
Skip ZIP artifact assembly but continue with annotation combining.
121-
Defaults to the value set below.
139+
The `svcsAnnotationsFile` property (singular) from plugin `0.1.0` has been replaced by
140+
`svcsAnnotationsFiles` (plural, a `ConfigurableFileCollection`).
141+
The old property still works but emits a deprecation warning and will be removed in a future release.
122142

123143
[source,gradle]
124144
----
145+
// Deprecated — emits a warning; delegates to svcsAnnotationsFiles.from(...)
125146
requirementsTool {
126-
skipAssembleZipArtifact = false
147+
svcsAnnotationsFile = file('...')
127148
}
128-
----
129-
130-
==== skipAttachZipArtifact
131-
132-
Skip artifact attachment for publishing.
133-
Defaults to the value set below.
134149
135-
[source,gradle]
136-
----
150+
// Preferred — additive
137151
requirementsTool {
138-
skipAttachZipArtifact = false
152+
svcsAnnotationsFiles.from(file('...'))
139153
}
140154
----
141-
142-
=== Notes
143-
144-
* All path parameters support both absolute and relative paths
145-
* The plugin executes after the `check` task by default
146-
* Test result paths support Ant-style pattern matching

0 commit comments

Comments
 (0)