feat: Add API tracker to compare local and upstream JSON APIs

.github/workflows/daily-api-tracker.yml

@@ -0,0 +1,59 @@
+name: Daily API Tracker
+
+on:
+  schedule:
+    # Run daily at 2 AM UTC
+    - cron: '0 2 * * *'
+  workflow_dispatch:  # Allow manual trigger for testing
+
+jobs:
+  track-api:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+
+    - name: Set up JDK 24
+      uses: actions/setup-java@v4
+      with:
+        java-version: '24'
+        distribution: 'temurin'
+
+    - name: Cache Maven dependencies
+      uses: actions/cache@v4
+      with:
+        path: ~/.m2
+        key: ${{ runner.os }}-m2-${{ hashFiles('**/pom.xml') }}
+        restore-keys: ${{ runner.os }}-m2
+
+    - name: Build project
+      run: mvn clean compile -DskipTests
+
+    - name: Run API Tracker
+      run: |
+        mvn exec:java \
+          -pl json-java21-api-tracker \
+          -Dexec.mainClass="io.github.simbo1905.tracker.ApiTrackerRunner" \
+          -Dexec.args="INFO" \
+          -Djava.util.logging.ConsoleHandler.level=INFO
+
+    - name: Create issue if differences found
+      if: failure()
+      uses: actions/github-script@v7
+      with:
+        script: |
+          const title = 'API differences detected between local and upstream';
+          const body = `The daily API tracker found differences between our local implementation and upstream.
+
+          Check the [workflow run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}) for details.
+
+          Date: ${new Date().toISOString().split('T')[0]}`;
+
+          github.rest.issues.create({
+            owner: context.repo.owner,
+            repo: context.repo.repo,
+            title: title,
+            body: body,
+            labels: ['api-tracking', 'upstream-sync']
+          });

.github/workflows/maven.yml

@@ -10,18 +10,15 @@ on:
 jobs:
   build:
     runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        java: [ '21', '22', '23', '24' ]
-    name: Build with JDK ${{ matrix.java }}
+    name: Build with JDK 24
 
     steps:
     - uses: actions/checkout@v4
 
-    - name: Set up JDK ${{ matrix.java }}
+    - name: Set up JDK 24
       uses: actions/setup-java@v4
       with:
-        java-version: ${{ matrix.java }}
+        java-version: '24'
         distribution: 'oracle'
 
     - name: Cache Maven dependencies

.gitignore

@@ -3,3 +3,5 @@ target/
 .idea/
 
 .claude/
+.aider*
+CLAUDE.md

CODING_STYLE_LLM.md

@@ -0,0 +1,133 @@
+# Java DOP Coding Standards ####################
+
+This file is a Gen AI summary of CODING_STYLE.md to use less tokens of context window. Read the original file for full details.
+
+IMPORTANT: We do TDD so all code must include targeted unit tests.
+IMPORTANT: Never disable tests written for logic that we are yet to write we do Red-Green-Refactor coding.
+
+## Core Principles
+
+* Use Records for all data structures. Use sealed interfaces for protocols.
+* Prefer static methods with Records as parameters
+* Default to package-private scope
+* Package-by-feature, not package-by-layer
+* Create fewer, cohesive, wide packages (functionality modules or records as protocols)
+* Use public only when cross-package access is required
+* Use JEP 467 Markdown documentation examples: `/// good markdown` not legacy `/** bad html */`
+* Apply Data-Oriented Programming principles and avoid OOP
+* Use Stream operations instead of traditional loops. Never use `for(;;)` with mutable loop variables use
+  `Arrays.setAll`
+* Prefer exhaustive destructuring switch expressions over if-else statements
+* Use destructuring switch expressions that operate on Records and sealed interfaces
+* Use anonymous variables in record destructuring and switch expressions
+* Use `final var` for local variables, parameters, and destructured fields
+* Apply JEP 371 "Local Classes and Interfaces" for cohesive files with narrow APIs
+
+## Data-Oriented Programming
+
+* Separate data (immutable Records) from behavior (never utility classes always static methods)
+* Use immutable generic data structures (maps, lists, sets) and take defense copies in constructors
+* Write pure functions that don't modify state
+* Leverage Java 21+ features:
+    * Records for immutable data
+    * Pattern matching for structural decomposition
+    * Sealed classes for exhaustive switches
+    * Virtual threads for concurrent processing
+
+## Package Structure
+
+* Use default (package-private) access as the standard. Do not use 'private' or 'public' by default.
+* Limit public to genuine cross-package APIs
+* Prefer package-private static methods. Do not use 'private' or 'public' by default.
+* Limit private to security-related code
+* Avoid anti-patterns: boilerplate OOP, excessive layering, dependency injection overuse
+
+## Constants and Magic Numbers
+
+* **NEVER use magic numbers** - always use enum constants
+* **NEVER write large if-else-if statements over known types** - will not be exhaustive and creates bugs when new types are added. Use exhaustive switch statements over bounded sets such as enum values or sealed interface permits
+
+## Functional Style
+
+* Combine Records + static methods for functional programming
+* Emphasize immutability and explicit state transformations
+* Reduce package count to improve testability
+* Implement Algebraic Data Types pattern with Function Modules
+* Modern Stream Programming
+* Use Stream API instead of traditional loops
+* Write declarative rather than imperative code
+* Chain operations without intermediate variables
+* Support immutability throughout processing
+* Example: `IntStream.range(0, 100).filter(i -> i % 2 == 0).sum()` instead of counting loops
+* Always use final variables in functional style.
+* Prefer `final var` with self documenting names over `int i` or `String s` but its not possible to do that on a `final` variable that is not yet initialized so its a weak preference not a strong one.
+* Avoid just adding new functionality to the top of a method to make an early return. It is fine to have a simple guard statement. Yet general you should pattern match over the input to do different things with the same method. Adding special case logic is a code smell that should be avoided.
+
+## Documentation using JEP 467 Markdown documentation
+
+IMPORTANT: You must not write JavaDoc comments that start with `/**` and end with `*/`
+IMPORTANT: You must "JEP 467: Markdown Documentation Comments" that start all lines with `///`
+
+Here is an example of the correct format for documentation comments:
+
+```java
+/// Returns a hash code value for the object. This method is
+/// supported for the benefit of hash tables such as those provided by
+/// [java.util.HashMap].
+///
+/// The general contract of `hashCode` is:
+///
+///   - Whenever it is invoked on the same object more than once during
+///     an execution of a Java application, the `hashCode` method
+///   - If two objects are equal according to the
+///     [equals][#equals(Object)] method, then calling the
+///   - It is _not_ required that if two objects are unequal
+///     according to the [equals][#equals(Object)] method, then
+///
+/// @return a hash code value for this object.
+/// @see     java.lang.Object#equals(java.lang.Object)
+```
+
+## Logging
+
+- Use Java's built-in logging: `java.util.logging.Logger`
+- Log levels: Use appropriate levels (FINE, FINER, INFO, WARNING, SEVERE)
+  - **FINE**: Production-level debugging, default for most debug output
+  - **FINER**: Verbose debugging, detailed internal flow, class resolution details
+  - **INFO**: Important runtime information
+- LOGGER is a static field: `static final Logger LOGGER = Logger.getLogger(ClassName.class.getName());` where use the primary interface or the package as the logger name with the logger package-private and shared across the classes when the package is small enough.
+- Use lambda logging for performance: `LOGGER.fine(() -> "message " + variable);`
+
+# Compile, Test, Debug Loop
+
+- **Check Compiles**: Focusing on the correct mvn module run without verbose logging and do not grep the output to see compile errors:
+  ```bash
+  ./mvn-test-no-boilerplate.sh -pl json-java21-api-tracker -Djava.util.logging.ConsoleHandler.level=SEVERE
+  ```
+- **Debug with Verbose Logs**: Use `-Dtest=` to focus on just one or two test methods, or one class, using more logging to debug the code:
+  ```bash
+  ./mvn-test-no-boilerplate.sh -pl json-java21-api-tracker -Dtest=XXX -Djava.util.logging.ConsoleHandler.level=FINER
+  ```
+- **No Grep Filtering**: Use logging levels to filter output, do not grep the output for compile errors, just run less test methods with the correct logging to reduce the output to a manageable size. Filtering hides problems and needs more test excution to find the same problems which wastes time.
+
+## Modern Java Singleton Pattern: Sealed Interfaces
+
+**Singleton Object Anti-Pattern**: Traditional singleton classes with private constructors and static instances are legacy should be avoided. With a functional style we can create a "package-private companion module" of small package-private methods with `sealed interfacee GoodSingletonModule permits Nothing { enum Nothing extends GoodSingletonModule{}; /* static functional methods here */ }`.
+
+### Assertions and Input Validation
+
+1.  On the public API entry points use `Objects.assertNonNull()` to ensure that the inputs are legal.
+2. After that on internal method that should be passed only valid data use `assert` to ensure that the data is valid.
+  - e.g. use `assert x==y: "unexpected x="+x+" y="+y;` as `mvn` base should be run with `-ea` to enable assertions.
+3. Often there is an `orElseThrow()` which can be used so the only reason to use `assert` is to add more logging to the error message.
+4. Consider using the validations of `Object` and `Arrays` and the like to ensure that the data is valid.
+  - e.g. `Objects.requireNonNull(type, "type must not be null")` or `Arrays.checkIndex(index, array.length)`.
+
+## JEP References
+
+[JEP 467](https://openjdk.org/jeps/467): Markdown Documentation in JavaDoc
+[JEP 371](https://openjdk.org/jeps/371): Local Classes and Interfaces
+[JEP 395](https://openjdk.org/jeps/395): Records
+[JEP 409](https://openjdk.org/jeps/409): Sealed Classes
+[JEP 440](https://openjdk.org/jeps/440): Record Patterns
+[JEP 427](https://openjdk.org/jeps/427): Pattern Matching for Switch

json-java21-api-tracker/pom.xml

@@ -0,0 +1,88 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <parent>
+        <groupId>io.github.simbo1905.json</groupId>
+        <artifactId>json-java21-parent</artifactId>
+        <version>0.1-SNAPSHOT</version>
+    </parent>
+
+    <artifactId>json-java21-api-tracker</artifactId>
+    <packaging>jar</packaging>
+
+    <name>API Tracker</name>
+
+    <properties>
+        <maven.compiler.release>24</maven.compiler.release>
+    </properties>
+
+    <dependencies>
+        <dependency>
+            <groupId>io.github.simbo1905.json</groupId>
+            <artifactId>json-java21</artifactId>
+            <version>${project.version}</version>
+        </dependency>
+        <!-- JUnit 5 for testing -->
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter-api</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter-engine</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.assertj</groupId>
+            <artifactId>assertj-core</artifactId>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+
+    <profiles>
+        <profile>
+            <id>relaxed</id>
+            <build>
+                <plugins>
+                    <plugin>
+                        <groupId>org.apache.maven.plugins</groupId>
+                        <artifactId>maven-compiler-plugin</artifactId>
+                        <configuration>
+                            <compilerArgs>
+                                <arg>-Xlint:all</arg>
+                            </compilerArgs>
+                        </configuration>
+                    </plugin>
+                </plugins>
+            </build>
+        </profile>
+    </profiles>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-compiler-plugin</artifactId>
+                <configuration>
+                    <release>${maven.compiler.release}</release>
+                    <compilerArgs>
+                        <arg>--enable-preview</arg>
+                        <arg>-Xlint:all</arg>
+                        <arg>-Werror</arg>
+                    </compilerArgs>
+                </configuration>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-surefire-plugin</artifactId>
+                <configuration>
+                    <argLine>--enable-preview</argLine>
+                </configuration>
+            </plugin>
+        </plugins>
+    </build>
+</project>