Feature/constrainable usage (#7)

* Extend Constrainable usage scenarios
* Add scenario to illustrate how the 'Constrainable' can be used for
  flow-control
* Remove SerentiyBDD and document reasoning
* Update Changelog
* Update documentation
* Boyscouting: clean up legacy github actions
* Update documentation
* Fixup: References from README
  * Attempt to resolve broken links by adding symlinks to the `.github` directory
  * see: issue #6 in github issue tracker
* Add code convention tests using ArchUnit
* Update library and fix issue in documentation
* Fix deprecated Assertion usage

---------

Co-authored-by: stijn-dejongh <stijn-dejongh@users.noreply.github.com>

Author: stijn-dejongh

.github/ADR.md

@@ -0,0 +1 @@
+../docs/ADR.md

.github/CHANGELOG.md

@@ -0,0 +1 @@
+../docs/CHANGELOG.md

.github/CONTRIBUTING.md

@@ -0,0 +1 @@
+../docs/CONTRIBUTING.md

.github/apidocs

@@ -0,0 +1 @@
+../docs/apidocs

.github/workflows/build.yml

@@ -13,26 +13,29 @@ jobs:
     runs-on: ubuntu-latest
     permissions:
       contents: write
+      pages: write
 
     steps:
       - uses: actions/checkout@v4
+        env:
+          GITHUB_TOKEN: ${{ secrets.REPO_TOKEN }}  # Needed to get PR information, if any
         with:
           ref: ${{ github.head_ref }}
-          fetch-depth: 2
 
       - name: Set up JDK 21
-        uses: actions/setup-java@v1
+        uses: actions/setup-java@v4
         with:
           java-version: 21
+          distribution: 'temurin'
+          cache: 'maven'
 
       - name: Branch name
         run: echo running on branch ${GITHUB_REF#refs/heads/}
 
       - name: Cache Maven packages
-        uses: actions/cache@v1
+        uses: actions/cache@v3
         with:
           path: ~/.m2
-          token: ${{ secrets.REPO_TOKEN }}
           key: ${{ runner.os }}-m2-${{ hashFiles('**/pom.xml') }}
           restore-keys: ${{ runner.os }}-m2
 
@@ -52,11 +55,10 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.REPO_TOKEN }}  # Needed to get PR information, if any
 
-      - name: Publish test report
-        run: cp -r target/site/serenity/* docs/serenity/
-
       - name: Commit JavaDocs
         uses: stefanzweifel/git-auto-commit-action@v5
+        env:
+          GITHUB_TOKEN: ${{ secrets.REPO_TOKEN }}  # Needed to get PR information, if any
         with:
           file_pattern: 'docs/*'
           commit_message: 'Update documentation'

.github/workflows/build_mainline.yml

@@ -11,28 +11,28 @@ jobs:
     runs-on: ubuntu-latest
     permissions:
       contents: write
+      pages: write
 
     steps:
       - uses: actions/checkout@v4
         with:
           ref: ${{ github.head_ref }}
           token: ${{ secrets.REPO_TOKEN }}
-          fetch-depth: 2
-
 
       - name: Set up JDK 21
-        uses: actions/setup-java@v1
+        uses: actions/setup-java@v4
         with:
           java-version: 21
+          distribution: 'temurin'
+          cache: 'maven'
 
       - name: Branch name
         run: echo running on branch ${GITHUB_REF#refs/heads/}
 
       - name: Cache Maven packages
-        uses: actions/cache@v1
+        uses: actions/cache@v3
         with:
           path: ~/.m2
-          token: ${{ secrets.REPO_TOKEN }}
           key: ${{ runner.os }}-m2-${{ hashFiles('**/pom.xml') }}
           restore-keys: ${{ runner.os }}-m2
 

docs/ADR.md

@@ -8,23 +8,36 @@
 
 see: [adr.github.io](https://adr.github.io/)
 
+---
+**Decisions:**  
+<!-- TOC -->
+* [Maintainability 1: Self-documenting tests](#maintainability-1-self-documenting-tests)
+<!-- TOC -->
+---
+
 ## Maintainability 1: Self-documenting tests
 
 **Problem:** Documenting the code and intended functionalities is tedious. It is often neglected and becomes outdated fast.
-**Decision:** Use the SerenityBDD framework, but avoid the use of `Gherkin` and `Cucumber`. Try to minimize the impact on the existing test when adding
-the self-documenting boilerplate.
+**Decision:** Rely on self-documenting tests. Write tests that document the code and intended functionalities.
 **Drivers:**
 
 * maintainability
 * extensibility
 * readability
 * minimalism
 
-**Goal:** Write tests that document the code and intended functionalities, use a framework to aggregate these intended 
+**Goal:** Write tests that document the code and intended functionalities, use a framework to aggregate these intended
 functionalities in a human-readable format.
 **Concerns:**
 
 * Complexity of adding yet another framework simply for test aggregation
 * Overhead of writing artifacts that are not directly related to the code
 * Results of the additional documentation will only be read by a few interested parties, most of them are developers who can quite easily read the
-  executable tests themselves and have less need for an aggregated report.
+  executable tests themselves and have less need for an aggregated report.
+
+**Considered Alternatives:**
+
+* Use of [Serenity BDD](https://serenity-bdd.github.io/): Removed after experimentation, as the usage was tedious and it tended to overload any PRs
+  by adding in a multitude of HTML files.
+* Custom reporting plugin, combining Javadoc, Markdown, and Jacoco reporting. Did not pursue further, as this would take a significant amount of
+  effort.

docs/CHANGELOG.md

@@ -31,6 +31,8 @@ Following changes are known:
 
 ### Added
 
+* Tests illustrating basic usage
+* Core functionality implementation
 * ReadMe.md file with project intent and outline
 * Root pom file with project name and outline
 * JavaDoc stylesheet
@@ -40,3 +42,5 @@ Following changes are known:
 ### Changed
 
 ### Removed
+
+* Removed Serenity BDD as a reporting framework, decision in ADR reflects reasoning

docs/CONTRIBUTING.md

@@ -139,7 +139,7 @@ void givenCheckedWithInvalidData_whenApplyingRule_itIsEvaluatedAsInvalid() {
 
     assertThat(result).is(invalid());
     assertThat(result.rationale())
-            .extracting(Rationale::details).asList()
+            .extracting(Rationale::details).asInstanceOf(LIST)
             .contains(failed("mustn't be blank"));
 }
 ```

docs/README.md

@@ -3,7 +3,7 @@
 A lightweight validation framework for the JVM, allowing for internal and external validation logic to be combined in a transparent and reusable
 way.
 
-| [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=sddevelopment-be_modular-validators&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=sddevelopment-be_modular-validators) | [![All Contributors](https://img.shields.io/github/all-contributors/sddevelopment-be/modular-validators?color=ee8449&style=flat-square)](#contributors) | [Test report](serenity/) | [JavaDoc](apidocs/) |
+| [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=sddevelopment-be_modular-validators&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=sddevelopment-be_modular-validators) | [![All Contributors](https://img.shields.io/github/all-contributors/sddevelopment-be/modular-validators?color=ee8449&style=flat-square)](#contributors) | [JavaDoc](https://sddevelopment-be.github.io/modular-validators/apidocs/) |
 
 ---