INIT: Java Library Functionality

.github/workflows/java-ci.yml

@@ -0,0 +1,138 @@
+name: Java CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+env:
+  JAVA_VERSION: '17'
+  GRADLE_OPTS: -Dorg.gradle.daemon=false
+
+jobs:
+  lint-and-check:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up JDK ${{ env.JAVA_VERSION }}
+      uses: actions/setup-java@v4
+      with:
+        java-version: ${{ env.JAVA_VERSION }}
+        distribution: 'temurin'
+
+    - name: Cache Gradle packages
+      uses: actions/cache@v4
+      with:
+        path: |
+          ~/.gradle/caches
+          ~/.gradle/wrapper
+        key: ${{ runner.os }}-gradle-${{ hashFiles('java/**/*.gradle*', 'java/**/gradle-wrapper.properties') }}
+        restore-keys: |
+          ${{ runner.os }}-gradle-
+
+    - name: Make gradlew executable
+      working-directory: ./java
+      run: chmod +x gradlew
+
+    - name: Run Checkstyle
+      working-directory: ./java
+      run: ./gradlew :library:checkstyleMain :library:checkstyleTest :example:checkstyleMain :example:checkstyleTest
+
+    - name: Generate schema classes
+      working-directory: ./java
+      run: ./gradlew :library:generateSchemaClasses
+
+  build-and-test:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up JDK ${{ env.JAVA_VERSION }}
+      uses: actions/setup-java@v4
+      with:
+        java-version: ${{ env.JAVA_VERSION }}
+        distribution: 'temurin'
+
+    - name: Cache Gradle packages
+      uses: actions/cache@v4
+      with:
+        path: |
+          ~/.gradle/caches
+          ~/.gradle/wrapper
+        key: ${{ runner.os }}-gradle-${{ hashFiles('java/**/*.gradle*', 'java/**/gradle-wrapper.properties') }}
+        restore-keys: |
+          ${{ runner.os }}-gradle-
+
+    - name: Make gradlew executable
+      working-directory: ./java
+      run: chmod +x gradlew
+
+    - name: Generate schema classes
+      working-directory: ./java
+      run: ./gradlew :library:generateSchemaClasses
+
+    - name: Build library
+      working-directory: ./java
+      run: ./gradlew :library:build -x test
+
+    - name: Run tests
+      working-directory: ./java
+      run: ./gradlew :library:test :example:test
+
+    - name: Generate test report
+      working-directory: ./java
+      run: ./gradlew :library:jacocoTestReport
+
+    - name: Upload test results
+      uses: actions/upload-artifact@v4
+      if: always()
+      with:
+        name: test-results
+        path: |
+          java/library/build/reports/tests/
+          java/library/build/reports/jacoco/
+
+    - name: Upload coverage to Codecov (optional)
+      uses: codecov/codecov-action@v4
+      if: success()
+      with:
+        file: java/library/build/reports/jacoco/test/jacocoTestReport.xml
+        flags: java
+        name: java-coverage
+        fail_ci_if_error: false
+
+  integration-test:
+    runs-on: ubuntu-latest
+    needs: build-and-test
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up JDK ${{ env.JAVA_VERSION }}
+      uses: actions/setup-java@v4
+      with:
+        java-version: ${{ env.JAVA_VERSION }}
+        distribution: 'temurin'
+
+    - name: Cache Gradle packages
+      uses: actions/cache@v4
+      with:
+        path: |
+          ~/.gradle/caches
+          ~/.gradle/wrapper
+        key: ${{ runner.os }}-gradle-${{ hashFiles('java/**/*.gradle*', 'java/**/gradle-wrapper.properties') }}
+        restore-keys: |
+          ${{ runner.os }}-gradle-
+
+    - name: Make gradlew executable
+      working-directory: ./java
+      run: chmod +x gradlew
+
+    - name: Run integration tests
+      working-directory: ./java
+      run: ./gradlew :library:test --tests "com.ditto.cot.CoTConverterIntegrationTest"
+
+    - name: Run XML round-trip tests
+      working-directory: ./java
+      run: ./gradlew :library:test --tests "com.ditto.cot.CoTXmlRoundTripTest"

.mcp.json

@@ -0,0 +1,18 @@
+{
+  "mcpServers": {
+    "linear": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-linear"
+      ]
+    },
+    "notion": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-notion"
+      ]
+    }
+  }
+}

CLAUDE.md

@@ -0,0 +1,84 @@
+# Claude Configuration for Ditto CoT Library
+
+This document provides specific instructions for Claude when working with the Ditto CoT library project.
+
+## Project Context
+
+Multi-language libraries (starting from a single managed JSON Schema) for translating between Cursor-on-Target (CoT) XML events and Ditto-compatible CRDT documents.
+
+## Linear Integration Guidelines
+
+**IMPORTANT:** When working with Linear tickets:
+
+- **NEVER** automatically change the status or state of Linear issues
+- **NEVER** transition issues between states (e.g., from "In Progress" to "Done")
+- **DO** read and reference Linear tickets for context
+- **DO** add comments to issues when explicitly requested
+- **DO NOT** modify any issue properties (assignee, labels, priority, etc.)
+- All status transitions should be handled manually by the development team
+
+## Development Guidelines
+
+### Testing Requirements
+
+- Always run tests before suggesting code completion
+- For Ditto CoT library development:
+  - All tests: `make test`
+- Suggest running lint and type checking if available
+- Verify that all tests pass before marking any task as complete
+
+### Build Commands
+
+- Build debug: `make clean`
+
+## Code Style Guidelines
+
+### General
+
+- Follow existing code conventions in the codebase
+- Use meaningful variable and function names
+- Maintain consistent indentation (check existing files)
+- Avoid adding debug prints or logs unless specifically requested
+
+### Java/Android/Kotlin Specific
+
+- Follow Java/Androind/Kotlin coding conventions
+- Use proper null safety patterns
+- Prefer data classes for data models
+- Use appropriate visibility modifiers
+
+### Rust Specific
+
+- Follow Rust coding conventions and idioms
+
+### C# Specific
+
+- Follow C# and .NET coding conventions and idioms
+
+### Documentation
+
+- Do not create documentation files unless explicitly requested
+- Keep code comments minimal and meaningful
+- Update existing documentation when making related changes
+
+## Important Reminders
+
+1. **Security**: Never commit sensitive information like API keys, passwords, or tokens
+2. **Dependencies**: Check existing dependencies before suggesting new ones
+3. **File Creation**: Prefer modifying existing files over creating new ones
+4. **Breaking Changes**: Always highlight potential breaking changes
+5. **Error Handling**: Implement proper error handling for all new features
+
+## Learning More About Ditto
+
+When you need more context about Ditto's architecture, conventions, or specific implementations:
+
+https://docs.ditto.live
+
+For Rust SDK: https://software.ditto.live/rust/Ditto/4.11.0/x86_64-unknown-linux-gnu/docs/dittolive_ditto/index.html
+For Java SDK: https://software.ditto.live/java/ditto-java/4.11.0-preview.1/api-reference/
+For C# SDK: https://software.ditto.live/dotnet/Ditto/4.11.0/api-reference/
+
+### When in Doubt, Ask First
+
+If you don't know how to do something, and you can't find accurate and up-to-date information from sources such as online documentation, content in Notion or Linear, or a tool's help output or man pages, then ask about an approach before doing it instead of guessing.

Makefile

@@ -19,9 +19,16 @@ clean-rust:
 # Java targets
 .PHONY: java
 java:
-	@echo "Building Java library..."
+	@echo "Cleaning previous build and generated sources..."
 	@if [ -f "java/build.gradle" ] || [ -f "java/build.gradle.kts" ]; then \
-		cd java && ./gradlew build -x test; \
+		cd java && \
+		rm -rf build/generated-src build/classes build/resources build/tmp build/libs build/reports build/test-results && \
+		mkdir -p src/main/java/com/ditto/cot/schema && \
+		find src/main/java/com/ditto/cot/schema -type f -name '*.java' -delete; \
+		echo "Generating Java classes from schema..."; \
+		./gradlew generateSchemaClasses; \
+		echo "Building Java library..."; \
+		./gradlew build -x test; \
 	else \
 		echo "Java build files not found. Skipping."; \
 	fi
@@ -61,13 +68,13 @@ test: test-rust test-java test-csharp
 .PHONY: test-rust
 test-rust:
 	@echo "Testing Rust library..."
-	@cd rust && cargo test --all-targets
+	@cd rust && cargo nextest run
 
 .PHONY: test-java
 test-java:
-	@echo "Testing Java library..."
+	@echo "Testing Java library and example..."
 	@if [ -f "java/build.gradle" ] || [ -f "java/build.gradle.kts" ]; then \
-		cd java && ./gradlew test; \
+		cd java && ./gradlew :library:test :example:test --console=rich --rerun-tasks; \
 	else \
 		echo "Java build files not found. Skipping tests."; \
 	fi

java/.gitignore

@@ -1,24 +1,94 @@
 # Gradle
 .gradle/
 build/
+!gradle/wrapper/gradle-wrapper.jar
+.gradletasknamecache
+
+# Build outputs
+bin/
+classes/
+out/
 
 # IDE files
 .idea/
 *.iml
-.classpath
+*.ipr
+*.iws
+*.classpath
 .project
 .settings/
-bin/
+.vscode/
+*.launch
+*.sublime-workspace
+*.sublime-project
 
 # Local configuration
 local.properties
+local.gradle
+.gradle.properties
 
 # Compiled class files
 *.class
 
 # Log files
 *.log
+logs/
 
 # Package files
 *.jar
-!gradle/wrapper/gradle-wrapper.jar
+*.war
+*.ear
+*.zip
+*.tar.gz
+*.rar
+
+# Virtual machine crash logs
+hs_err_pid*
+
+# Generated files and directories
+**/generated-src/
+**/generated/
+**/generated_test/
+
+# Test reports and coverage
+**/test-results/
+**/test-results-*/
+**/test-output-*/
+**/test-report-*/
+**/reports/
+**/coverage/
+**/jacoco/
+
+# OS specific files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Build scan files
+build/scan*/
+build/reports/scan/
+
+# Gradle Daemon files
+.gradle/native
+.gradle/daemon/
+.gradle/vcs-1/
+.gradle/buildOutputCleanup/
+.gradle/build-scan-data/
+.gradle/buildOutputCleanup/
+.gradle/checksums/
+.gradle/configuration-cache/
+.gradle/daemon/
+.gradle/jdks/
+.gradle/normalization/
+.gradle/notifications/
+.gradle/workers/
+.gradle/workers/
+.gradle/wrapper/dists/
+
+# Ditto specific
+target/
+buildSrc/build/

java/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ditto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.