fix/build aqlhelp

.github/workflows/ci.yml

@@ -2,9 +2,9 @@ name: CI
 
 on:
   push:
-    branches: [ master ]
+    branches: [master]
   pull_request:
-    branches: [ master ]
+    branches: [master]
 
 permissions:
   contents: read
@@ -17,8 +17,8 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-java@v4
         with:
-          java-version: '21'
-          distribution: 'temurin'
+          java-version: "21"
+          distribution: "temurin"
       - uses: gradle/actions/setup-gradle@v4
 
       - name: Compile
@@ -75,8 +75,8 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-java@v4
         with:
-          java-version: '21'
-          distribution: 'temurin'
+          java-version: "21"
+          distribution: "temurin"
       - uses: gradle/actions/setup-gradle@v4
 
       - run: ./gradlew checkstyleMain
@@ -96,8 +96,8 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-java@v4
         with:
-          java-version: '21'
-          distribution: 'temurin'
+          java-version: "21"
+          distribution: "temurin"
 
       - name: Compile main sources with javac
         run: |
@@ -116,8 +116,8 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-java@v4
         with:
-          java-version: '21'
-          distribution: 'temurin'
+          java-version: "21"
+          distribution: "temurin"
       - uses: gradle/actions/setup-gradle@v4
 
       - run: ./gradlew spotbugsMain
@@ -129,3 +129,48 @@ jobs:
           name: spotbugs-report
           path: build/reports/spotbugs/
           retention-days: 14
+
+  spotless:
+    name: Spotless (format)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-java@v4
+        with:
+          java-version: "21"
+          distribution: "temurin"
+      - uses: gradle/actions/setup-gradle@v4
+
+      - run: ./gradlew spotlessCheck
+
+  docs:
+    name: Docs (AqlHelp)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-java@v4
+        with:
+          java-version: "21"
+          distribution: "temurin"
+      - uses: gradle/actions/setup-gradle@v4
+
+      - name: Generate CQL manual
+        run: ./gradlew generateHelp
+
+      - name: Verify docs generated properly
+        run: |
+          set -euo pipefail
+          test -d help || { echo "::error::help/ was not produced"; exit 1; }
+          for f in index.html syntax.html options.html examples.html logo.html; do
+            test -s "help/$f" || { echo "::error::missing or empty help/$f"; exit 1; }
+          done
+
+      - name: Upload generated docs
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: cql-manual
+          path: help/
+          retention-days: 14

build.gradle

@@ -10,6 +10,10 @@ group = 'org.categoricaldata'
 version = '1.0.0'
 
 java {
+    toolchain {
+        languageVersion = JavaLanguageVersion.of(21)
+    }
+    // Keep producing Java 17 bytecode for runtime compatibility.
     sourceCompatibility = JavaVersion.VERSION_17
     targetCompatibility = JavaVersion.VERSION_17
 }
@@ -100,18 +104,35 @@ jacocoTestCoverageVerification {
 
 // --- Spotless (formatting) ---
 spotless {
-    // Only check files that changed vs HEAD — won't flag existing unformatted code
-    ratchetFrom 'HEAD'
+    // Only check files that changed vs a baseline — won't flag the existing unformatted
+    // codebase. Locally, ratchet against HEAD (your uncommitted changes). In CI, a clean
+    // checkout has no diff vs HEAD, so ratchet against the base branch to check what the
+    // PR actually changed. GitHub Actions sets CI=true.
+    ratchetFrom(System.getenv('CI') ? 'origin/master' : 'HEAD')
     java {
         target 'src/**/*.java'
         targetExclude '**/*Test.java', '**/*TestHelpers.java', '**/easik/**', '**/com/**', '**/OilExample.java'
-        googleJavaFormat()
+        googleJavaFormat('1.28.0')
         removeUnusedImports()
         trimTrailingWhitespace()
         endWithNewline()
     }
 }
 
+// --- Documentation generation ---
+// Runs AqlHelp.main, which generates the CQL HTML manual into the help/ directory
+// (relative to the project root). The forked JVM calls System.exit(0) on success.
+tasks.register('generateHelp', JavaExec) {
+    group = 'documentation'
+    description = 'Generates the CQL HTML manual into the help/ directory.'
+    dependsOn 'classes'
+    mainClass = 'catdata.cql.exp.AqlHelp'
+    classpath = sourceSets.main.runtimeClasspath
+    // Examples may touch AWT; force headless so it runs on CI with no display.
+    systemProperty 'java.awt.headless', 'true'
+    jvmArgs '--add-opens', 'java.base/java.lang=ALL-UNNAMED'
+}
+
 // Git pre-commit hook: runs spotlessCheck before each commit
 tasks.register('installGitHook', Copy) {
     from 'config/hooks/pre-commit'