feat(hexagonal-spring-rules): add new architecture rules and examples

.gitignore

@@ -46,7 +46,7 @@ build/
 # IntelliJ IDEA
 *.iml
 *.iws
-out/
+/out/
 
 # VS Code
 /worktrees/
@@ -55,3 +55,4 @@ out/
 gradle-plugin-publishing.md
 sedr-library-maven-central-publishing.md
 
+/**/*prompts.md

examples/architecture-validator/hexagonal-spring-cycle-detection/README.adoc

@@ -0,0 +1,82 @@
+= Hexagonal Spring Cycle Detection Example
+:toc: left
+
+This example demonstrates package cycle detection in adapter packages via `CycleFreedomTest`.
+It also documents the `CycleFreedomTest` slice-pattern bug fix that was required to make this check
+effective in realistically nested base packages — see "Why this example exists" below.
+
+== Files and Purpose
+
+[cols="1,2"]
+|===
+|File |Purpose
+
+|`src/main/java/.../cycledetection/adapter/persistence/OrderRepositoryAdapter.java`
+|Adapter package A. Depends on `adapter.notification.OrderNotifier`.
+
+|`src/main/java/.../cycledetection/adapter/notification/OrderNotifier.java`
+|Adapter package B. Depends back on `OrderRepositoryAdapter`, closing the cycle.
+
+|`src/main/java/.../cycledetection/application/service/OrderService.java`
+|Plain application service that depends only on an outbound port — kept compliant so the only failure is the
+cycle itself.
+|===
+
+== Configuration
+
+[source,groovy]
+----
+architectureValidator {
+    basePackage = 'com.arc_e_tect.example.spring.cycledetection'
+    useBuiltInHexagonalRulePack = false
+}
+----
+
+No special properties are needed — `CycleFreedomTest` runs against the plugin's default `adapters` pattern
+(`..adapter..`/`..adapters..`).
+
+== Why this example exists
+
+`CycleFreedomTest` builds an ArchUnit slice pattern from the configured `adapters` package root. The
+original implementation stripped a leading `..` from that pattern (e.g. `..adapters..` became `adapters`),
+which anchors the resulting pattern to the *start* of a class's fully-qualified name. For any realistic,
+multi-segment base package like `com.arc_e_tect.example.spring.cycledetection`, no class's FQN actually
+starts with `adapters.` — so the check matched zero classes and passed vacuously, regardless of real cycles.
+This example's base package is deliberately nested several segments deep so it would have silently passed
+under the old, buggy pattern; it now correctly fails.
+
+== Run
+
+[source,bash]
+----
+./gradlew build
+./gradlew testArchitecture
+----
+
+== Expected violations
+
+The two adapter classes depend on each other, forming a two-package cycle:
+
+[source,java]
+----
+// adapter.persistence.OrderRepositoryAdapter
+public OrderRepositoryAdapter(OrderNotifier notifier) { ... }   // depends on adapter.notification
+
+// adapter.notification.OrderNotifier
+public OrderNotifier(OrderRepositoryAdapter repositoryAdapter) { ... } // depends back on adapter.persistence
+----
+
+`CycleFreedomTest.adapterPackagesShouldBeFreeOfCycles` fails and reports the cycle between
+`adapter.persistence` and `adapter.notification`. Every other rule class passes for this fixture.
+
+== Reports
+
+The Gradle HTML report is under `build/reports/architecture-validator/html/`.
+The XML report is under `build/reports/architecture-validator/xml/`.
+
+== Fix
+
+Break the dependency loop so `adapter.notification` no longer depends on `adapter.persistence` — for
+example, have `OrderRepositoryAdapter` publish through a port or event mechanism instead of calling into
+`OrderNotifier` directly, or move the shared collaboration point into a package neither adapter owns. Keep
+adapter package dependencies acyclic to preserve maintainable boundaries.

examples/architecture-validator/hexagonal-spring-cycle-detection/build.gradle

@@ -0,0 +1,45 @@
+plugins {
+    id 'jacoco'
+    id 'java'
+    alias(libs.plugins.architecture.validator.iff)
+}
+
+group = 'com.arc-e-tect.example.spring'
+version = '0.0.1'
+
+java {
+    toolchain {
+        languageVersion = JavaLanguageVersion.of(21)
+    }
+}
+
+repositories {
+    mavenLocal()
+    mavenCentral()
+}
+
+dependencies {
+    implementation libs.spring.context.iff
+    testArchitectureImplementation libs.architecture.validator.hexagonal.spring.rules.iff
+}
+
+architectureValidator {
+    basePackage = 'com.arc_e_tect.example.spring.cycledetection'
+    useBuiltInHexagonalRulePack = false
+
+}
+
+tasks.named('jacocoTestReport') {
+    reports {
+        xml.required = true
+        html.required = true
+    }
+}
+
+tasks.named('testArchitecture', Test) {
+    ignoreFailures = false
+}
+
+tasks.named('check') {
+    dependsOn tasks.named('testArchitecture')
+}

examples/architecture-validator/hexagonal-spring-cycle-detection/gradle/libs.versions.toml

@@ -0,0 +1,16 @@
+## Generated by $ ./gradlew refreshVersionsCatalog
+
+[plugins]
+
+architecture-validator-iff = { id = "com.arc-e-tect.architecture-validator", version.ref = "architecture-validator-iff" }
+
+[versions]
+
+architecture-validator-iff = "0.0.1"
+architecture-validator-hexagonal-spring-rules-iff = "1.0.0-PRERELEASE"
+spring-context-iff = "7.0.8"
+
+[libraries]
+
+architecture-validator-hexagonal-spring-rules-iff = { module = "com.arc-e-tect.architecture-validator:architecture-validator-hexagonal-spring-rules", version.ref = "architecture-validator-hexagonal-spring-rules-iff" }
+spring-context-iff = { module = "org.springframework:spring-context", version.ref = "spring-context-iff" }

examples/architecture-validator/hexagonal-spring-cycle-detection/gradle/wrapper/gradle-wrapper.properties

@@ -0,0 +1,9 @@
+distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-9.6.1-bin.zip
+networkTimeout=10000
+retries=0
+retryBackOffMs=500
+validateDistributionUrl=true
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists