Refactoring structure -- WIP

core/pom.xml

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <parent>
+        <groupId>be.sddevelopment</groupId>
+        <artifactId>modular-validators</artifactId>
+        <version>1.0.0-SNAPSHOT</version>
+        <relativePath>../pom.xml</relativePath>
+    </parent>
+
+    <artifactId>core</artifactId>
+
+
+</project>

docs/decision_records/ADR.md

@@ -0,0 +1,19 @@
+# Architectural Decision Records (ADRs)
+
+> An Architectural Decision (AD) is a justified software design choice that addresses a functional or non-functional requirement that is
+> architecturally significant. An Architecturally Significant Requirement (ASR) is a requirement that has a measurable effect on a software system’s
+> architecture and quality. An Architectural Decision Record (ADR) captures a single AD and its rationale; the collection of ADRs created and
+> maintained in a project constitute its decision log. All these are within the topic of Architectural Knowledge Management (AKM), but ADR usage can
+> be extended to design and other decisions (“any decision record”).
+
+see: [adr.github.io](https://adr.github.io/)
+
+## Decision Records
+
+| name                                                   |    status     | date       | tags |
+|:-------------------------------------------------------|:-------------:|------------|-----:|
+| [Self-documenting tests](./self_documenting_tests.md)  | `implemented` | 2023-11-26 |      | 
+| [Validation DSL](./validation_dsl.md)                  |  `approved`   | 2024-11-26 |      |
+
+
+## Maintainability 1: 

docs/ADR.md → docs/decision_records/self_documenting_tests.md

@@ -1,21 +1,4 @@
-# Architectural Decision Records (ADRs)
-
-> An Architectural Decision (AD) is a justified software design choice that addresses a functional or non-functional requirement that is
-> architecturally significant. An Architecturally Significant Requirement (ASR) is a requirement that has a measurable effect on a software system’s
-> architecture and quality. An Architectural Decision Record (ADR) captures a single AD and its rationale; the collection of ADRs created and
-> maintained in a project constitute its decision log. All these are within the topic of Architectural Knowledge Management (AKM), but ADR usage can
-> be extended to design and other decisions (“any decision record”).
-
-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
+# Self-documenting tests
 
 **Problem:** Documenting the code and intended functionalities is tedious. It is often neglected and becomes outdated fast.
 **Decision:** Rely on self-documenting tests. Write tests that document the code and intended functionalities.
@@ -40,4 +23,4 @@ functionalities in a human-readable format.
 * 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.
+  effort.

docs/decision_records/validation_dsl.md

@@ -0,0 +1,58 @@
+# Generate validator code from PlantUML custom theme specification
+
+## Context
+
+Most organizations have business-minded individuals or non-software engineers defining the specifications of the software (internal clients, product owners, analysts, managers, end-users).
+
+## Problem
+Business validation rules are tedious to maintain, as the translation from business specification into executable validation code involves multiple hand-overs and knowledge-extraction events. In the end, there is seldom time to maintain this consistently.
+
+Current "Behaviour Driven Development" approaches lack the direct feedback to the end users, and are rather verbose
+(cfr. Cucumber, Gherkin, Finesse, JBehave, ...)
+
+## Intent
+
+* ’maintainability:‘ significant increase
+* ‘adaptability:‘ significant increase
+
+## Solution
+
+* Work with file based validation inputs only, to simplify process and allow for extensibility. ( If your data can be written to a file, it can be validated. Covering most of the real-world use cases for backend BDD approaches).
+* Use a minimal plantUML based specification
+* Write a plantUML to executable code parser
+
+## Reasoning
+
+* Out of the box documentation due to PlantUML visualisation
+* Out of the box syntax checks due to PlantUML
+* Compatibility with most tech stacks
+* Specification can be kept, even if validation framework is removed
+
+## Considered alternatives
+
+* **Write a custom`<insert BDD spec>`  to `ModularValidator` implementation**:  rejected due to stack/dependency impact.
+* **Write a Kotlin based DSL**:  rejected due to language onboarding requirements.
+* **Use an existing tool**: rejected as that would defeat the purpose of this project.
+
+# References
+
+* [JBehave](https://jbehave.org/?r=qal-bddtt)
+* [Finesse](https://fitnesse.org/)
+* [Cucumber](https://cucumber.io/?r=qal-bddtt)
+* [Serenity](https://serenity-bdd.github.io/)
+
+# Example: Potential DSL API
+
+```plantUML
+
+ValidatorFor(".*IDENTIFIABLE_PART_OF_FILE_NAME.*\\.csv") {
+   RecordIdentifier('ROW_ID')
+   FieldMatches('FIELD_NAME', 'MAY_NOT_BE_EMPTY')
+   FieldExists('JOSKE_WAS_HERE')
+   
+   ValidationCase("description") {
+     RecordExists('12345')
+     RecordHasValue('12345', 'FIELD_NAME', 'expectedValue')
+   }
+}
+```

dsl/pom.xml

@@ -0,0 +1,23 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <parent>
+        <groupId>be.sddevelopment</groupId>
+        <artifactId>modular-validators</artifactId>
+        <version>1.0.0-SNAPSHOT</version>
+        <relativePath>../pom.xml</relativePath>
+    </parent>
+
+    <artifactId>dsl</artifactId>
+
+    <properties>
+        <maven.compiler.source>21</maven.compiler.source>
+        <maven.compiler.target>21</maven.compiler.target>
+        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+    </properties>
+
+
+</project>

pom.xml

@@ -15,6 +15,11 @@
         an object.
     </description>
 
+    <modules>
+        <module>core</module>
+        <module>dsl</module>
+    </modules>
+
     <distributionManagement>
         <repository>
             <id>github</id>
@@ -163,7 +168,7 @@
                 <version>3.5.0</version>
                 <configuration>
                     <stylesheet>maven</stylesheet>
-                    <javadocDirectory>src/main/javadoc</javadocDirectory>
+                    <javadocDirectory>core/src/main/javadoc</javadocDirectory>
                     <addStylesheets>
                         <resources>/styles/stylesheet.css</resources>
                     </addStylesheets>
@@ -223,7 +228,7 @@
                 <version>3.5.0</version>
                 <configuration>
                     <stylesheet>maven</stylesheet>
-                    <javadocDirectory>src/main/javadoc</javadocDirectory>
+                    <javadocDirectory>core/src/main/javadoc</javadocDirectory>
                     <addStylesheets>
                         <resources>${project.basedir}/javadoc/stylesheet.css</resources>
                     </addStylesheets>