Skip to content

fix: restore deprecated svcsAnnotationsFile setter and auto-wire task dependencies #53

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jimisola merged 4 commits into from
Apr 19, 2026
Merged

fix: restore deprecated svcsAnnotationsFile setter and auto-wire task dependencies #53

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
89d2e55
fix: restore deprecated svcsAnnotationsFile setter for backwards comp…
jimisola Apr 18, 2026
fb1552c
feat: auto-wire task dependencies and warn on missing annotation files
jimisola Apr 18, 2026
7561c46
docs: update Antora docs to reflect auto-wiring and svcsAnnotationsFi…
jimisola Apr 18, 2026
8b6d2ba
fix: resolve Spring format violation and add missing javadoc @param tag
jimisola Apr 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 55 additions & 6 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,28 +12,77 @@ 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.

## Installation

Add the plugin to your `build.gradle`:

```groovy
plugins {
id 'io.github.reqstool.gradle-plugin' version '0.1.0'
id 'io.github.reqstool.gradle-plugin' version '0.1.1'
}

requirementsTool {
datasetPath = file('docs/reqstool')
}
```

tasks.named('build') {
finalizedBy tasks.named('assembleRequirements')
}
The `assembleRequirements` task runs automatically as part of `build`. No additional wiring is required.

## Configuration

All properties are optional. Defaults match the standard Gradle project layout.

| Property | Type | Default | Description |
|---|---|---|---|
| `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 |
| `svcsAnnotationsFiles` | `ConfigurableFileCollection` | Auto-discovered from all non-main source sets | SVCs annotations YAML files, one per test source set (e.g. `test`, `integrationTest`) |
| `svcsAnnotationsFile` _(deprecated)_ | `Object` | — | **Deprecated since 0.1.1.** Use `svcsAnnotationsFiles.from(...)` instead. Delegates to `svcsAnnotationsFiles` and emits a `WARN` log. |
| `outputDirectory` | `RegularFileProperty` | `build/reqstool` | Output directory for the ZIP artifact and combined annotations file |
| `datasetPath` | `RegularFileProperty` | `reqstool/` (project directory) | Directory containing `requirements.yml` and optional supporting files |
| `testResults` | `ListProperty<String>` | `["build/test-results/**/*.xml"]` | Ant-style glob patterns for test result XML files to include in the ZIP |
| `skip` | `Property<Boolean>` | `false` | Skip all plugin execution |
| `skipAssembleZipArtifact` | `Property<Boolean>` | `false` | Skip ZIP assembly; annotations are still combined into `annotations.yml` |
| `skipAttachZipArtifact` | `Property<Boolean>` | `false` | Skip attaching the ZIP artifact to Maven publications |

### Dataset directory

The `datasetPath` directory must contain at minimum a `requirements.yml` file. Optional files in the same directory are included if present:

| File | Required |
|---|---|
| `requirements.yml` | Yes |
| `software_verification_cases.yml` | No |
| `manual_verification_results.yml` | No |

### Overriding auto-discovered annotation files

tasks.named('assembleRequirements') {
dependsOn tasks.named('test')
To replace the auto-discovered SVCs annotation files with explicit paths (also disables auto-wired compile dependencies for test source sets):

```groovy
requirementsTool {
setSvcsAnnotationsFiles(
file('custom/path/test-annotations.yml'),
file('custom/path/it-annotations.yml')
)
}
```

## Task reference

### `assembleRequirements`

Group: `build`

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`.

**Auto-wired dependencies** (when the `java` plugin is applied):

- 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`

## Usage

```bash
Expand Down
192 changes: 100 additions & 92 deletions docs/modules/ROOT/pages/configuration.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,146 +1,154 @@
== Configuration
= Configuration

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

=== Complete Configuration Example
== Configuration reference

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

// Path to SVCS annotations YAML
// Default: build/generated-test-sources/test-annotations/resources/annotations.yml
svcsAnnotationsFile = file('build/custom-path/test-annotations.yml')
|`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

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

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

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

// Skip entire plugin execution
// Default: false
skip = false
|`datasetPath`
|`RegularFileProperty`
|`reqstool/` (project directory)
|Directory containing `requirements.yml` and optional supporting files

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

// Skip artifact attachment for publishing
// Default: false
skipAttachZipArtifact = false
}
----
|`skip`
|`Property<Boolean>`
|`false`
|Skip all plugin execution

=== Configuration Parameters
|`skipAssembleZipArtifact`
|`Property<Boolean>`
|`false`
|Skip ZIP assembly; annotations are still combined into `annotations.yml`

==== requirementsAnnotationsFile
|`skipAttachZipArtifact`
|`Property<Boolean>`
|`false`
|Skip attaching the ZIP artifact to Maven publications
|===

The `requirementsAnnotationsFile` parameter specifies the path to the requirements annotations file.
Defaults to the value set below.
== Dataset directory

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

==== svcsAnnotationsFile
[cols="1,1",options="header"]
|===
|File |Required

The `svcsAnnotationsFile` parameter specifies the path to the SVCS (Software Verification Cases) annotations file.
Defaults to the value set below.
|`requirements.yml`
|Yes

[source,gradle]
----
requirementsTool {
svcsAnnotationsFile = file('build/generated-test-sources/test-annotations/resources/annotations.yml')
}
----
|`software_verification_cases.yml`
|No

|`manual_verification_results.yml`
|No
|===

==== outputDirectory
== Minimal configuration

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

[source,gradle]
----
requirementsTool {
outputDirectory = file('build/reqstool')
datasetPath = file('docs/reqstool')
}
----

==== datasetPath

The `datasetPath` parameter specifies the path to the dataset directory containing requirements.yml and optional files.
Defaults to the value set below.
== Complete configuration example

[source,gradle]
----
requirementsTool {
datasetPath = file('./reqstool')
requirementsAnnotationsFile =
file('build/generated/sources/annotationProcessor/java/main/resources/annotations.yml')

// svcsAnnotationsFiles is a file collection — use .from() to add files additively
svcsAnnotationsFiles.from(
file('build/generated/sources/annotationProcessor/java/test/resources/annotations.yml')
)

outputDirectory = file('build/reqstool')
datasetPath = file('docs/reqstool')
testResults = ['build/test-results/**/*.xml']
skip = false
skipAssembleZipArtifact = false
skipAttachZipArtifact = false
}
----

==== testResults
== Overriding auto-discovered annotation files

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

[source,gradle]
----
requirementsTool {
testResults = ['build/test-results/**/*.xml', 'build/custom-tests/**/*.xml']
setSvcsAnnotationsFiles(
file('custom/path/test-annotations.yml'),
file('custom/path/it-annotations.yml')
)
}
----

==== skip
== Auto-wired task dependencies

Skip the execution of the entire plugin.
Defaults to the value set below.
When the `java` plugin is applied, the plugin automatically wires:

[source,gradle]
----
requirementsTool {
skip = false
}
----
* `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`

No manual `dependsOn` or `finalizedBy` blocks are needed in the consuming project.

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.

==== skipAssembleZipArtifact
== Deprecation notice

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

[source,gradle]
----
// Deprecated — emits a warning; delegates to svcsAnnotationsFiles.from(...)
requirementsTool {
skipAssembleZipArtifact = false
svcsAnnotationsFile = file('...')
}
----

==== skipAttachZipArtifact

Skip artifact attachment for publishing.
Defaults to the value set below.

[source,gradle]
----
// Preferred — additive
requirementsTool {
skipAttachZipArtifact = false
svcsAnnotationsFiles.from(file('...'))
}
----

=== Notes

* All path parameters support both absolute and relative paths
* The plugin executes after the `check` task by default
* Test result paths support Ant-style pattern matching
Loading
Loading