Multi-module reactor, ArchUnit guards, and a filter-sql-adapter module

.releaserc.json

@@ -7,14 +7,14 @@
     [
       "@semantic-release/exec",
       {
-        "prepareCmd": "./mvnw -B versions:set -DnewVersion=${nextRelease.version} -DgenerateBackupPoms=false"
+        "prepareCmd": "./mvnw -B versions:set -DnewVersion=${nextRelease.version} -DgenerateBackupPoms=false -DprocessAllModules=true"
       }
     ],
     "@semantic-release/github",
     [
       "@semantic-release/git",
       {
-        "assets": ["CHANGELOG.md", "pom.xml"],
+        "assets": ["CHANGELOG.md", "pom.xml", "*/pom.xml"],
         "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
       }
     ]

CONTRIBUTING.md

@@ -53,4 +53,4 @@ the properties in `pom.xml`:
 ```
 
 Set `jacoco.line.min` from the module's actually-measured coverage (see the report under
-`target/site/jacoco/`), and ratchet it up over time rather than guessing a threshold now.
+`filter-core/target/site/jacoco/`), and ratchet it up over time rather than guessing a threshold now.

README.md

@@ -23,11 +23,22 @@ Requires JDK 21.
 ```xml
 <dependency>
   <groupId>org.sequeless</groupId>
-  <artifactId>sequeless-filter</artifactId>
+  <artifactId>filter-core</artifactId>
   <version>0.0.0-SNAPSHOT</version>
 </dependency>
 ```
 
+## Modules
+
+| Module | Coordinates | Contents |
+| --- | --- | --- |
+| [`filter-core`](filter-core) | `org.sequeless:filter-core` | The DSL: AST model, ANTLR 4 grammar and parser, serializer, operator and field registries, completion utilities. |
+| [`filter-sql-adapter`](filter-sql-adapter) | `org.sequeless:filter-sql-adapter` | Translates a parsed `FilterNode` AST into raw, parameterized SQL via a hexagonal `QueryBuilder` vendor port. See [docs/sql-adapter.md](docs/sql-adapter.md). |
+
+The repository root is a `pom`-packaged aggregator/parent (`org.sequeless:sequeless-filter`) that
+ships no code — it holds the single shared version, dependency management, and build plugins. All
+modules are released together from that one version.
+
 ## Build
 
 ```bash
@@ -42,6 +53,7 @@ install is required.
 ## Documentation
 
 - [Filter DSL reference](docs/filter-dsl.md) — grammar, operators, serialization, completion.
+- [SQL adapter](docs/sql-adapter.md) — translating a `FilterNode` AST into parameterized SQL.
 - Architecture decisions live under [`docs/adr/`](docs/adr/).
 
 ## Contributing

docs/adr/0001-split-the-build-into-a-maven-reactor.md

@@ -0,0 +1,61 @@
+# 0001. Split the build into a Maven reactor
+
+- Status: accepted
+- Date: 2026-07-30
+
+## Context
+
+`sequeless-filter` was a single `<packaging>jar</packaging>` module holding the entire filter DSL:
+AST model, ANTLR 4 grammar/parser, serializer, operator and field registries, and completion
+utilities.
+
+A SQL adapter (`FilterNode` AST → SQL) is arriving as a second module. It must not inherit the
+ANTLR runtime dependency it never uses — a single-jar layout has no way to express "this
+dependency belongs to one consumer of the DSL, not the DSL itself."
+
+Publishing doesn't exist for this project today: there's no `<distributionManagement>` and no
+`mvn deploy` step anywhere in CI, so there's no real external consumer whose published coordinates
+this restructuring could break.
+
+## Decision
+
+Convert the root `pom.xml` into a `pom`-packaged aggregator/parent that keeps the existing
+coordinates `org.sequeless:sequeless-filter`, and move all existing source under a new
+`filter-core` module (`org.sequeless:filter-core`).
+
+- **One shared, parent-inherited version.** Children declare no `<version>` of their own.
+- **`jackson-databind` and `antlr4-runtime` move to `<dependencyManagement>`-only.** Each module
+  must opt in by redeclaring the dependency it actually needs — this is what lets the upcoming
+  `filter-sql-adapter` module avoid pulling in ANTLR.
+- **`lombok`, `junit-jupiter`, `assertj-core`, `mockito-core`, `archunit-junit5` stay as plain,
+  parent-inherited `<dependencies>`.** Every module wants all five, so redeclaring them per module
+  would buy nothing.
+- **All build plugins stay in the parent's inherited `<build><plugins>`, with one exception:**
+  `flatten-maven-plugin` moves to `<pluginManagement>` with no `<skip>` element, and the aggregator
+  never declares/binds it in its own `<build><plugins>`. Each child declares it bare
+  (groupId + artifactId only) and inherits the full managed configuration.
+
+## Consequences
+
+- **Published coordinates change** from `sequeless-filter` to `filter-core` for the actual DSL jar.
+  This is accepted and intentionally left unmarked as a breaking change in commit messages, since
+  nothing is published today and there's no real external consumer to break.
+- **`.releaserc.json` must commit `*/pom.xml`** (alongside the root `pom.xml`) as a release asset.
+  `versions:set -DprocessAllModules=true` rewrites both the aggregator's `<version>` and each
+  child's `<parent><version>` — omitting the child glob would leave the child POM's parent
+  reference stale after a release commit.
+- **JaCoCo coverage reports are now produced per module** (e.g. `filter-core/target/site/jacoco/`),
+  with no aggregate report across the reactor. Deliberate, not an oversight — a coverage aggregator
+  module isn't needed until there's a concrete reason to view coverage across modules in one report.
+- **`sonar-project.properties` was deliberately left untouched.** CI's SonarCloud job has never
+  actually executed an analysis — every run to date logs "SONAR_TOKEN not set; skipping SonarCloud
+  scan." and exits 0. Whether `sonar-project.properties` (a SonarScanner-CLI-style file) is even
+  read by the Maven-integrated `sonar:sonar` goal CI invokes remains unconfirmed: there's no
+  "ANALYSIS SUCCESSFUL ... dashboard?id=..." log line to point at a working configuration to
+  preserve or fix. Speculatively migrating Sonar properties into the parent POM without that
+  confirmation risks guessing wrong about the project key or paths it depends on.
+
+  **Follow-up for whoever enables `SONAR_TOKEN` later:** check the resulting analysis log's
+  `dashboard?id=` line, then either fix `sonar.coverage.jacoco.xmlReportPaths` to point at
+  `filter-core/target/site/jacoco/jacoco.xml`, or migrate the relevant Sonar properties into the
+  parent POM's `<properties>` and retire `sonar-project.properties`.

docs/filter-dsl.md

@@ -93,3 +93,8 @@ function-argument index the cursor sits in.
 
 A field's `CompletionProvider` is optional and embedder-supplied (e.g. backing a `status` field's value
 completion with the live set of distinct values) — fields without one simply offer no value candidates.
+
+## See also
+
+- [SQL adapter](sql-adapter.md) — translating a parsed `FilterNode` AST into parameterized SQL
+  against a relational database, via `filter-sql-adapter`.