Issue #153 treat upstream fetch failure as drift in the API tracker

hasDifferences now returns true when missingUpstream > 0, the
fingerprint includes UPSTREAM_ERROR classes so issue dedup works for
fetch-failure drift, and the summary renders a Missing Upstream section
listing each affected class and error. Previously a dead upstream
fetch path reported all-clear, which is what blinded the daily tracker
after the upstream incubator move (see #145).

Verify: mvnd -pl json-java21-api-tracker -am clean test (14 tracker
tests green, 3 new); full reactor clean verify = 1679 tests 0 skipped;
ci.yml exp_tests 1676 -> 1679.

Author: simbo1905

.github/workflows/ci.yml

@@ -39,7 +39,7 @@ jobs:
                       for k in totals: totals[k]+=int(r.get(k,'0'))
                   except Exception:
                       pass
-          exp_tests=1676
+          exp_tests=1679
           exp_skipped=0
           if totals['tests']!=exp_tests or totals['skipped']!=exp_skipped:
               print(f"Unexpected test totals: {totals} != expected tests={exp_tests}, skipped={exp_skipped}")

json-java21-api-tracker/src/main/java/io/github/simbo1905/tracker/ApiTracker.java

@@ -947,7 +947,7 @@ static String fetchUpstreamSource(String className) {
     /// @param report the full comparison report
     /// @return 7-character fingerprint or "0000000" if no differences
     static String generateFingerprint(JsonObject report) {
-        if (getDifferentApiCount(report) == 0) {
+        if (!hasDifferences(report)) {
             return "0000000";
         }
 
@@ -959,6 +959,13 @@ static String generateFingerprint(JsonObject report) {
             final var diffObj = (JsonObject) diff;
             final var status = ((JsonString) diffObj.asMap().get("status")).asString();
 
+            if ("UPSTREAM_ERROR".equals(status)) {
+                // Fetch failures are drift too: include them so the issue
+                // dedup fingerprint is distinct per affected class set.
+                stableLines.add(((JsonString) diffObj.asMap().get("className")).asString() + ":UPSTREAM_ERROR");
+                continue;
+            }
+            
             if (!"DIFFERENT".equals(status)) continue;
 
             final var className = ((JsonString) diffObj.asMap().get("className")).asString();
@@ -1009,6 +1016,21 @@ private static long getDifferentApiCount(JsonObject report) {
         return 0;
     }
 
+    /// Extracts the missingUpstream count from a report summary
+    /// @param report the comparison report
+    /// @return the count of classes whose upstream fetch or parse failed
+    private static long getMissingUpstreamCount(JsonObject report) {
+        final var summary = (JsonObject) report.asMap().get("summary");
+        if (summary == null) {
+            return 0;
+        }
+        final var missingUpstreamValue = summary.asMap().get("missingUpstream");
+        if (missingUpstreamValue instanceof JsonNumber num) {
+            return num.asLong();
+        }
+        return 0;
+    }
+
     /// Generates a terse human-readable summary of the API differences
     /// Suitable for GitHub issue body
     /// @param report the full comparison report
@@ -1068,6 +1090,23 @@ static String generateSummary(JsonObject report) {
             }
         }
 
+        if (missingUpstream > 0) {
+            sb.append("## Missing Upstream\n\n");
+            sb.append("These classes could not be fetched or parsed upstream. A fetch failure is drift: the tracker cannot confirm we are current.\n\n");
+            for (final var diff : differences.asList()) {
+                final var diffObj = (JsonObject) diff;
+                final var status = ((JsonString) diffObj.asMap().get("status")).asString();
+                
+                if (!"UPSTREAM_ERROR".equals(status)) continue;
+                
+                final var className = ((JsonString) diffObj.asMap().get("className")).asString();
+                final var errorValue = diffObj.asMap().get("error");
+                final var error = errorValue instanceof JsonString js ? js.asString() : "unknown error";
+                sb.append("- ⚠️ **").append(className).append("**: `").append(error).append("`\n");
+            }
+            sb.append("\n");
+        }
+        
         sb.append("---\n");
         final var timestamp = ((JsonString) report.asMap().get("timestamp")).asString();
         sb.append("*Generated by API Tracker on ").append(timestamp.split("T")[0]).append("*\n");
@@ -1077,8 +1116,8 @@ static String generateSummary(JsonObject report) {
 
     /// Checks if there are any API differences in the report
     /// @param report the comparison report
-    /// @return true if differentApi > 0
+    /// @return true if differentApi > 0 or missingUpstream > 0
     static boolean hasDifferences(JsonObject report) {
-        return getDifferentApiCount(report) > 0;
+        return getDifferentApiCount(report) > 0 || getMissingUpstreamCount(report) > 0;
     }
 }

json-java21-api-tracker/src/test/java/io/github/simbo1905/tracker/ApiTrackerTest.java

@@ -9,8 +9,10 @@
 
 import jdk.incubator.java.util.json.JsonBoolean;
 import jdk.incubator.java.util.json.JsonArray;
+import jdk.incubator.java.util.json.JsonNumber;
 import jdk.incubator.java.util.json.JsonObject;
 import jdk.incubator.java.util.json.JsonString;
+import jdk.incubator.java.util.json.Json;
 
 import java.util.Set;
 import java.util.Map;
@@ -234,4 +236,108 @@ void testNormalizeTypeName() {
                 .isEqualTo("String");
         }
     }
+
+    @Nested
+    @DisplayName("Drift Detection Gates")
+    class DriftDetectionGateTests {
+
+        private static JsonObject upstreamErrorDiff(String className, String error) {
+            return JsonObject.of(Map.of(
+                "className", JsonString.of(className),
+                "status", JsonString.of("UPSTREAM_ERROR"),
+                "error", JsonString.of(error)
+            ));
+        }
+
+        private static JsonObject report(long differentApi, long missingUpstream, JsonArray differences) {
+            return JsonObject.of(Map.of(
+                "timestamp", JsonString.of("2026-08-30T00:00:00Z"),
+                "summary", JsonObject.of(Map.of(
+                    "totalClasses", JsonNumber.of(differentApi + missingUpstream),
+                    "matchingClasses", JsonNumber.of(0),
+                    "differentApi", JsonNumber.of(differentApi),
+                    "missingUpstream", JsonNumber.of(missingUpstream)
+                )),
+                "differences", differences
+            ));
+        }
+
+        @Test
+        @DisplayName("Upstream fetch failures must count as drift, not all-clear")
+        void testHasDifferencesTreatsUpstreamErrorAsDrift() {
+            LoggingControl.setupCleanLogging();
+            java.util.logging.Logger.getLogger(getClass().getName())
+                .info(() -> "TEST: testHasDifferencesTreatsUpstreamErrorAsDrift");
+            final var allErrors = report(0, 2, JsonArray.of(java.util.List.of(
+                upstreamErrorDiff("JsonNumber", "NOT_FOUND: Upstream file not found"),
+                upstreamErrorDiff("JsonObject", "HTTP_ERROR: Status 500")
+            )));
+
+            assertThat(ApiTracker.hasDifferences(allErrors))
+                .as("a fully-blind detector run (every class UPSTREAM_ERROR) must report drift")
+                .isTrue();
+
+            final var mixed = report(1, 1, JsonArray.of(java.util.List.of(
+                upstreamErrorDiff("JsonNumber", "NOT_FOUND: Upstream file not found"),
+                JsonObject.of(Map.of(
+                    "className", JsonString.of("JsonValue"),
+                    "status", JsonString.of("DIFFERENT"),
+                    "differences", JsonArray.of(java.util.List.of())
+                ))
+            )));
+            assertThat(ApiTracker.hasDifferences(mixed)).isTrue();
+        }
+
+        @Test
+        @DisplayName("Fingerprint covers UPSTREAM_ERROR classes and is stable and distinct")
+        void testFingerprintCoversUpstreamErrors() {
+            LoggingControl.setupCleanLogging();
+            java.util.logging.Logger.getLogger(getClass().getName())
+                .info(() -> "TEST: testFingerprintCoversUpstreamErrors");
+            final var none = report(0, 0, JsonArray.of(java.util.List.of()));
+            assertThat(ApiTracker.generateFingerprint(none)).isEqualTo("0000000");
+
+            final var errorsA = report(0, 2, JsonArray.of(java.util.List.of(
+                upstreamErrorDiff("JsonNumber", "NOT_FOUND: Upstream file not found"),
+                upstreamErrorDiff("JsonObject", "NOT_FOUND: Upstream file not found")
+            )));
+            final var errorsAgain = report(0, 2, JsonArray.of(java.util.List.of(
+                upstreamErrorDiff("JsonObject", "NOT_FOUND: Upstream file not found"),
+                upstreamErrorDiff("JsonNumber", "NOT_FOUND: Upstream file not found")
+            )));
+            final var errorsB = report(0, 1, JsonArray.of(java.util.List.of(
+                upstreamErrorDiff("JsonNumber", "NOT_FOUND: Upstream file not found")
+            )));
+
+            final var fpA = ApiTracker.generateFingerprint(errorsA);
+            assertThat(fpA)
+                .as("fetch-failure drift must not hash to the no-differences sentinel")
+                .isNotEqualTo("0000000");
+            assertThat(ApiTracker.generateFingerprint(errorsAgain))
+                .as("same error set in different order must fingerprint identically")
+                .isEqualTo(fpA);
+            assertThat(ApiTracker.generateFingerprint(errorsB))
+                .as("different error sets must fingerprint differently")
+                .isNotEqualTo(fpA);
+        }
+
+        @Test
+        @DisplayName("Summary renders a Missing Upstream section for fetch failures")
+        void testSummaryRendersMissingUpstreamSection() {
+            LoggingControl.setupCleanLogging();
+            java.util.logging.Logger.getLogger(getClass().getName())
+                .info(() -> "TEST: testSummaryRendersMissingUpstreamSection");
+            final var allErrors = report(0, 2, JsonArray.of(java.util.List.of(
+                upstreamErrorDiff("JsonNumber", "NOT_FOUND: Upstream file not found (possibly deleted or renamed)"),
+                upstreamErrorDiff("JsonObject", "HTTP_ERROR: Status 500")
+            )));
+
+            final var summary = ApiTracker.generateSummary(allErrors);
+
+            assertThat(summary).contains("Missing Upstream");
+            assertThat(summary).contains("JsonNumber");
+            assertThat(summary).contains("JsonObject");
+            assertThat(summary).contains("NOT_FOUND: Upstream file not found (possibly deleted or renamed)");
+        }
+    }
 }