Add API comparison report documenting upstream changes

Generated detailed report showing 7 classes with breaking API changes in upstream OpenJDK sandbox

Co-authored-by: simbo1905 <[email protected]>

Author: Copilot

updates/api-check-2025-12-02.md

@@ -0,0 +1,131 @@
+# API Tracker Report - December 2, 2025
+
+## Summary
+
+The API tracker was successfully run against the upstream OpenJDK sandbox JSON API (branch: `json`).
+
+**Status:** SIGNIFICANT API CHANGES DETECTED
+
+- **Total Classes:** 11
+- **Matching Classes:** 4 (36%)
+- **Different API:** 7 (64%)
+- **Missing Upstream:** 0
+
+## Key Findings
+
+The upstream has undergone substantial API evolution with **breaking changes** across multiple core classes.
+
+### 1. Json Class - Method Renaming (Breaking Change)
+
+The main API entry point has renamed its conversion methods:
+
+| Local (Current)   | Upstream (New)  | Impact       |
+|-------------------|-----------------|--------------|
+| `fromUntyped()`   | `toJson()`      | Breaking     |
+| `toUntyped()`     | `fromJson()`    | Breaking     |
+
+**Migration Impact:** All code using these methods will need updates.
+
+### 2. JsonArray - API Expansion
+
+| Change Type | Method      | Impact       |
+|-------------|-------------|--------------|
+| Removed     | `values()`  | Breaking     |
+| Added       | `elements()`| Replacement  |
+| Added       | `array()`   | New feature  |
+
+### 3. JsonBoolean - Accessor Renamed
+
+| Local (Current) | Upstream (New) | Impact   |
+|-----------------|----------------|----------|
+| `value()`       | `bool()`       | Breaking |
+
+### 4. JsonNumber - Major Refactoring
+
+Significant changes to number handling:
+
+**Removed Methods:**
+- `toNumber()`
+- `toBigDecimal()`
+
+**Added Methods:**
+- `number()` - returns JsonNumber itself
+- `toLong()` - direct long conversion
+- `toDouble()` - direct double conversion
+
+**Changed Methods:**
+- `of(BigDecimal)` → `of(long)` - Parameter type changed
+
+**Impact:** High - Affects all numeric value handling code.
+
+### 5. JsonObject - API Addition
+
+| Change Type | Method     | Impact      |
+|-------------|------------|-------------|
+| Added       | `object()` | Non-breaking|
+
+### 6. JsonParseException - Error Reporting Changes
+
+| Local (Current)   | Upstream (New)       | Impact   |
+|-------------------|----------------------|----------|
+| `getErrorRow()`   | `getErrorLine()`     | Breaking |
+| `getErrorColumn()`| `getErrorPosition()` | Breaking |
+
+### 7. JsonString - Accessor Renamed
+
+| Local (Current) | Upstream (New) | Impact   |
+|-----------------|----------------|----------|
+| `value()`       | `string()`     | Breaking |
+
+## Unchanged Classes
+
+The following classes have no API changes:
+- `JsonAssertionException`
+- `JsonNull`
+- `JsonValue`
+- `package-info`
+
+## Impact Assessment
+
+### Breaking Changes Count: 7 classes affected
+
+1. **High Impact:** Json, JsonNumber
+2. **Medium Impact:** JsonArray, JsonParseException
+3. **Low Impact:** JsonBoolean, JsonString, JsonObject
+
+### Naming Conventions
+
+The upstream appears to be moving toward:
+- Shorter, more direct method names (`bool()` vs `value()`)
+- More specific type conversion methods (`toLong()`, `toDouble()`)
+- Better semantic naming (`fromJson/toJson` vs `fromUntyped/toUntyped`)
+- Consistent terminology (`line/position` vs `row/column`)
+
+## Recommendations
+
+1. **Do Not Update Immediately:** These are breaking changes requiring a major version bump
+2. **Create Migration Guide:** Document all API changes for users
+3. **Consider Deprecation Path:** Add deprecated methods pointing to new equivalents
+4. **Update Documentation:** Warn users about unstable upstream API
+5. **Monitor Upstream:** Check for stabilization signals before syncing
+
+## Technical Details
+
+- **Timestamp:** 2025-12-02T15:21:49.231451636Z
+- **Local Package:** jdk.sandbox.java.util.json
+- **Upstream Package:** java.util.json
+- **Upstream Source:** https://github.com/openjdk/jdk-sandbox/tree/json
+- **Runtime Java Version:** 21.0.9
+- **Comparison Duration:** 1.377 seconds
+
+## Next Steps
+
+1. ✅ Document the upstream changes (this file)
+2. ⏳ Wait for upstream API stabilization
+3. ⏳ Create tracking issue for future sync
+4. ⏳ Plan migration strategy when upstream stabilizes
+5. ⏳ Consider maintaining compatibility shims
+
+## Conclusion
+
+The upstream OpenJDK sandbox JSON API is actively evolving with significant breaking changes. This backport should remain on the current API until upstream shows signs of stabilization. Users should be aware that this is an experimental API subject to change.