Split into Maven multi-module (engine + server); rename to cuckooDB

[JinBa1]

What

Two changes, one per commit:

1. Rename to cuckooDB — the Java package (…blazedb → …cuckoodb), entry-point class (BlazeDB → CuckooDB), Maven coordinates, and docs are renamed. No behaviour change; query output is byte-identical.
2. Maven multi-module split — a parent aggregator POM with two modules:
   • engine/ (cuckoodb-engine) — the query engine, free of any web framework (JSqlParser + commons-csv only). All existing code, tests, sample queries, the CLI fat-jar, JMH benchmarks, and JaCoCo move here wholesale.
   • server/ (cuckoodb-server) — a skeleton module that depends on the engine, ready for a REST gateway. No web framework is introduced yet; a placeholder class compile-links an engine type to prove the wiring.

Why

The engine is meant to be a pure, embeddable query core. Splitting the build makes that boundary structural: a future network layer depends on the engine, never the reverse — enforced by Maven rather than by convention.

Notes

• samples/ moved into engine/, so the sample-query golden tests resolve their paths under the module's working directory.
• .gitignore, the CI Codecov report path, and the README/AGENTS build & run commands are updated for the new layout (-pl engine where needed).
• The GitHub repository URLs (badges, clone) are intentionally unchanged — the repository slug is not being renamed here.

Testing

• Reactor ./mvnw clean test — green.
• 20 sample queries — byte-identical output (SampleQueryRunner and CuckooDBTest.testAllSampleQueries).
• cuckoodb-server compiles against cuckoodb-engine; the engine fat-jar runs a query end-to-end.

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

❌ Patch coverage is 0% with 3 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
.../com/github/jinba1/cuckoodb/SampleQueryRunner.java	0.00%	2 Missing ⚠️
...main/java/com/github/jinba1/cuckoodb/CuckooDB.java	0.00%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[JinBa1]

@claude review this PR

[claude]

Claude finished @JinBa1's task in 2m 27s —— View job

---

PR Review: Split into Maven multi-module (engine + server); rename to cuckooDB

• Read CLAUDE.md for repo-specific guidelines
• Examine PR diff and key structural files
• Review parent POM and module POMs
• Review CI/CD configuration changes
• Review server module structure
• Review documentation changes (README, AGENTS.md)
• Compile findings and post review

---

This is a clean, well-scoped structural PR. The rename is mechanical and correct throughout; the multi-module split is logically sound with Maven enforcing the server → engine direction. A few things worth addressing, ordered by severity:

---

Issues

1. JMH annotation processor version is hardcoded in engine/pom.xml instead of inheriting from the parent

engine/pom.xml lines 52–58:

<testAnnotationProcessorPaths>
  <path>
    <groupId>org.openjdk.jmh</groupId>
    <artifactId>jmh-generator-annprocess</artifactId>
    <version>1.37</version>   
  </path>
</testAnnotationProcessorPaths>

The root pom.xml already manages jmh-generator-annprocess at 1.37 in <dependencyManagement>, but <annotationProcessorPaths> / <testAnnotationProcessorPaths> entries don't pull versions from <dependencyManagement> — Maven treats them as a separate resolution path. The versions happen to match today, but if the JMH version is ever bumped in the parent, this hardcoded <version> will silently stay behind. Fix: introduce a <jmh.version>1.37</jmh.version> property in the parent POM and reference it in both the <dependencyManagement> entries and this <path> block. Fix this →

2. SampleQueryRunner lives in src/main/java and will be packaged into the fat-jar

engine/src/main/java/com/github/jinba1/cuckoodb/SampleQueryRunner.java is a developer-facing integration harness. Because it's in main sources rather than test sources, it is compiled into the fat-jar along with the engine. This is benign (no runtime penalty), but it means end-users who embed cuckoodb-engine as a library dependency also pull in SampleQueryRunner. For a library module that's meant to be "embeddable", test utilities generally live in src/test/java.

The trade-off noted in the README (exec:exec requires a -Dexec.classpathScope=test invocation regardless of which source set it lives in) means this is callable either way. If the intent is to keep it visible in the JAR as a self-test entry point, that's a deliberate choice — worth a brief comment in the POM or the class explaining why it's not in test sources.

3. Fragile working-directory assumption in SampleQueryRunner

Path projectRoot = Paths.get("").toAbsolutePath();  // assumes CWD == engine/
Path dbDir      = projectRoot.resolve("samples/db");

This works when invoked via ./mvnw -pl engine exec:exec because the exec plugin's working directory for a module is that module's base directory. But it will silently fail if someone runs the bundled fat-jar from the repo root or any other directory. The README's new "Or run each query through the CLI" section already shows the engine-scoped paths, so the discrepancy is easy to miss. A cleaner approach: accept an optional samples/ base-path argument and fall back to the CWD-relative default, so the failure mode is an explicit "samples/db not found" rather than a cryptic path error.

---

Observations (no action required)

Codecov 0% patch coverage — Codecov is flagging the main() bodies in CuckooDB.java and SampleQueryRunner.java. Both are CLI entry points; unit tests correctly target CuckooDB.run() instead. This is expected and not a real gap.

Server skeleton is well-done — ServerPlaceholder.describe() referencing QueryResult.class.getSimpleName() is a neat way to guarantee a compile-time dependency exercise without dead imports. The comment block in server/pom.xml explaining why no Spring dependency enters yet is helpful for future contributors.

Module boundary is correct — cuckoodb-server depends on cuckoodb-engine; the engine has no dependency on the server. Maven will enforce this: if a future commit tries to add a server class to the engine, it will fail to compile. That's exactly the structural guarantee the PR description promises.

.gitignore update is complete — all three test-output paths now point to engine/src/test/resources/…, matching the new layout. The REPORT_*.md pattern is a nice addition.

CI change is minimal and correct — pointing Codecov at engine/target/site/jacoco/jacoco.xml is right; the server module has no coverage to report yet. The reactor-level ./mvnw clean test step remains unchanged and will correctly test both modules (with the server module simply having no tests to run).

---

Summary

The rename and multi-module split are executed correctly, the boundary is structurally enforced, and all docs/paths are updated consistently. The main item worth acting on before merge is issue 1 (JMH version drift risk). Issues 2 and 3 are lower priority but worth tracking as the project grows toward a real server module.

[JinBa1]

Thanks for the review. Triaged all three:

1. JMH annotation-processor version — fixed in e14089c. Added a <jmh.version>1.37</jmh.version> property in the parent and referenced it from both the <dependencyManagement> JMH entries and the engine's <testAnnotationProcessorPaths> path, so a bump now touches one place. Note the path keeps an explicit <version> (now the property) on purpose: under maven-compiler-plugin 3.11.0 the annotation-processor-path version is not inherited from <dependencyManagement> (that landed in 3.12.0), so it has to stay set — the property just removes the drift risk you flagged. Reactor build + full suite still green.

2. SampleQueryRunner in src/main ships in the fat-jar — deferred (pre-existing). It already lived in src/main on main; this PR is a pure rename + structural split that moves code wholesale without repackaging, so changing its source set is out of scope here. It's intentionally a runnable self-test entry point in the jar. Agreed it's worth revisiting when the engine is published as a real library artifact — tracking it as a follow-up.

3. SampleQueryRunner working-directory assumption — deferred (pre-existing, now documented). The Paths.get("") CWD dependence is unchanged from main; what the split changed is that the correct CWD is now engine/. Rather than alter engine code in a structural slice, this PR documents the correct invocation (exec:exec, which forks with workingDirectory = engine/) in both README and AGENTS, and notes that exec:java must not be used. An optional samples/ base-path argument with an explicit "not found" failure is a reasonable hardening follow-up.

Codecov 0% patch — as you noted, those are the CuckooDB/SampleQueryRunner main() bodies; tests target CuckooDB.run(). Not a real gap.