ci: set up Spotless linting in CI (#351)

.github/workflows/build.yml

@@ -124,6 +124,8 @@ jobs:
     if: github.event_name == 'pull_request'
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 0
 
       - name: Reclaim disk space
         working-directory: .github/scripts

.github/workflows/spotless.yml

@@ -0,0 +1,52 @@
+name: Spotless
+
+on:
+  pull_request:
+    branches:
+      - main
+  workflow_dispatch:
+
+concurrency:
+  group: "workflow = ${{ github.workflow }}, ref = ${{ github.event.ref }}, pr = ${{ github.event.pull_request.id }}"
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+defaults:
+  run:
+    shell: bash
+
+permissions:
+  contents: read
+
+jobs:
+  spotless-check:
+    runs-on: ubuntu-latest
+    name: spotless-check
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 0
+
+      - name: Reclaim disk space
+        working-directory: .github/scripts
+        shell: bash
+        run: ./ci-reclaim-disk-space.sh
+
+      - name: Set up Java 17
+        uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5.2.0
+        with:
+          java-version: 17
+          distribution: temurin
+
+      - name: Setup Gradle
+        uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5.0.2
+
+      - name: Run Spotless check
+        run: |
+          if ! ./gradlew --no-daemon -Pjava.version=17 spotlessCheck; then
+            echo "::error title=Spotless check failed::Formatting violations were found."
+            echo "Fix options:"
+            echo "  1) Run: ./gradlew --no-daemon spotlessApply"
+            echo "  2) Ensure your IDE honors .editorconfig and reformat changed files"
+            echo "Then commit and push the updated files."
+            exit 1
+          fi

.spotless/import-order.txt

@@ -0,0 +1,23 @@
+0=\#
+1=
+2=java
+3=
+4=javax
+5=
+6=jakarta
+7=
+8=org
+9=
+10=com
+11=
+12=ai
+13=
+14=org.apache.commons
+15=
+16=org.springframework
+17=
+18=io.quarkus
+19=
+20=io
+21=
+22=\*

CONTRIBUTING.md

@@ -101,6 +101,28 @@ If you have not done so on this machine, you need to:
 
 The project has a `.editorconfig` file checked into the root. Please make sure the rules in there are adhered to by your IDE.
 
+## Build
+
+To run a full build locally:
+
+```bash
+./gradlew --no-daemon build
+```
+
+To run code linting locally:
+
+```bash
+./gradlew --no-daemon spotlessCheck
+```
+
+To automatically apply formatting fixes:
+
+```bash
+./gradlew --no-daemon spotlessApply
+```
+
+`spotlessCheck` enforces Java formatting plus basic whitespace rules (LF line endings, no trailing whitespace, and final newline). IDE style settings are still driven by `.editorconfig`.
+
 ## The small print
 
 This project is an open source project, please act responsibly, be nice, polite and enjoy!

buildSrc/build.gradle.kts

@@ -10,6 +10,7 @@ repositories {
 dependencies {
   implementation("org.yaml:snakeyaml:2.6")
   implementation(libs.lombok.gradle)
+  implementation(libs.spotless.gradle)
 }
 
 // Read root gradle.properties

buildSrc/src/main/kotlin/docling-java-shared.gradle.kts

@@ -2,6 +2,7 @@ plugins {
   id("docling-shared")
   `java-library`
   `jacoco`
+  id("com.diffplug.spotless")
 }
 
 repositories {
@@ -41,6 +42,20 @@ jacoco {
   toolVersion = libs.findVersion("jacoco").get().toString()
 }
 
+spotless {
+  ratchetFrom("origin/main")
+
+  java {
+    toggleOffOn()
+    target("src/*/java/**/*.java")
+
+    // Only going to enforce import order for now
+    importOrderFile("${rootProject.layout.projectDirectory}/.spotless/import-order.txt")
+
+    // Project maintainers need to decide what the formatting rules should be
+  }
+}
+
 tasks.withType<Test>().configureEach {
   // Use JUnit Platform for unit tests.
   useJUnitPlatform()

gradle/libs.versions.toml

@@ -9,6 +9,7 @@ junit = "6.0.3"
 lombok = "1.18.42"
 lombok-gradle = "9.2.0"
 module-info = "1.14"
+spotless = "8.2.1"
 semver4j = "6.0.0"
 slf4j = "2.0.17"
 testcontainers = "2.0.3"
@@ -26,6 +27,7 @@ awaitility = { group = "org.awaitility", name = "awaitility", version.ref = "awa
 
 # lombok-gradle
 lombok-gradle = { group = "io.freefair.lombok", name = "io.freefair.lombok.gradle.plugin", version.ref = "lombok-gradle" }
+spotless-gradle = { group = "com.diffplug.spotless", name = "spotless-plugin-gradle", version.ref = "spotless" }
 
 # Jackson
 jackson-annotations = { group = "com.fasterxml.jackson.core", name = "jackson-annotations" }