fix(tracker-lens): recognise api-detector-core's current semver schemaVersion header line

tracker-lens/src/main/java/com/arc_e_tect/gradle/trackerlens/tracker/ApiContractTrackerSource.java

@@ -40,12 +40,22 @@ public class ApiContractTrackerSource implements TrackerSource {
     private static final Logger LOGGER = Logging.getLogger(ApiContractTrackerSource.class);
 
     /**
-     * Matches an optional file-level {@code {"schemaVersion":N}} marker line, silently skipped
-     * rather than logged as malformed if present as this file's first line. {@code api-detector-core}
-     * does not write this marker yet - this is forward-compatible tolerance only, so that whenever
-     * it does start writing one, this reader already handles it without another release here.
+     * Matches the legacy, bare-integer {@code {"schemaVersion":N}} marker line
+     * {@code api-detector-core} wrote before it tracked a semver format version, silently skipped
+     * rather than logged as malformed if present as this file's first line.
      */
-    private static final Pattern SCHEMA_VERSION_LINE = Pattern.compile("^\\{\"schemaVersion\":(\\d+)\\}$");
+    private static final Pattern LEGACY_SCHEMA_VERSION_LINE = Pattern.compile("^\\{\"schemaVersion\":(\\d+)\\}$");
+
+    /**
+     * Matches the current {@code {"schemaVersion":"x.y.z"[,"migrations":[...]]}} marker line
+     * {@code api-detector-core}'s {@code ContractHistoryStore} writes - a semver format version,
+     * optionally followed by its own persisted migration audit trail. Skipped the same way
+     * {@link #LEGACY_SCHEMA_VERSION_LINE} is; this reader has no need for either the version or
+     * the audit trail itself, only for not misreading the line that carries them as a malformed
+     * record.
+     */
+    private static final Pattern SCHEMA_VERSION_LINE = Pattern.compile(
+            "^\\{\"schemaVersion\":\"[^\"]+\"(?:,\"migrations\":\\[.*])?}$");
 
     private static final String STRING_FIELD = "\"((?:[^\"\\\\]|\\\\.)*)\"";
     private static final String NULLABLE_STRING_FIELD = "(?:null|" + STRING_FIELD + ")";
@@ -82,7 +92,8 @@ public List<LifecycleRecord> read(File historyFile) {
             if (line.isBlank()) {
                 continue;
             }
-            if (i == 0 && SCHEMA_VERSION_LINE.matcher(line).matches()) {
+            if (i == 0 && (LEGACY_SCHEMA_VERSION_LINE.matcher(line).matches()
+                    || SCHEMA_VERSION_LINE.matcher(line).matches())) {
                 continue;
             }
             LifecycleRecord record = parseLine(line);

tracker-lens/src/test/java/com/arc_e_tect/gradle/trackerlens/tracker/ApiContractTrackerSourceTest.java

@@ -159,6 +159,40 @@ void readShouldSkipALeadingSchemaVersionMarkerLineWithoutLoggingItAsMalformed()
         assertThat(records).extracting(LifecycleRecord::id).containsExactly("ep4");
     }
 
+    @Test
+    @DisplayName("readShouldSkipALeadingSemverSchemaVersionMarkerLineWithoutLoggingItAsMalformed")
+    void readShouldSkipALeadingSemverSchemaVersionMarkerLineWithoutLoggingItAsMalformed() throws IOException {
+        Path file = writeFile(
+                "{\"schemaVersion\":\"1.1.0\"}",
+                "{\"fingerprint\":\"ep4\",\"verb\":\"GET\",\"path\":\"/orders\","
+                + "\"declaringClass\":null,"
+                + "\"declaredAt\":\"2026-01-01T00:00:00Z\",\"implementedAt\":null,"
+                + "\"stubbedAt\":null,"
+                + "\"verifiedAt\":null,\"lastSeenAt\":null,\"removedAt\":null}");
+
+        List<LifecycleRecord> records = source.read(file.toFile());
+
+        assertThat(records).extracting(LifecycleRecord::id).containsExactly("ep4");
+    }
+
+    @Test
+    @DisplayName("readShouldSkipALeadingSemverSchemaVersionMarkerLineWithAMigrationAuditTrailWithoutLoggingItAsMalformed")
+    void readShouldSkipALeadingSemverSchemaVersionMarkerLineWithMigrationsWithoutLoggingItAsMalformed()
+            throws IOException {
+        Path file = writeFile(
+                "{\"schemaVersion\":\"1.1.0\",\"migrations\":[{\"fromVersion\":\"1.0.0\","
+                + "\"toVersion\":\"1.1.0\",\"migratedAt\":\"2026-08-27T00:00:00Z\"}]}",
+                "{\"fingerprint\":\"ep4\",\"verb\":\"GET\",\"path\":\"/orders\","
+                + "\"declaringClass\":null,"
+                + "\"declaredAt\":\"2026-01-01T00:00:00Z\",\"implementedAt\":null,"
+                + "\"stubbedAt\":null,"
+                + "\"verifiedAt\":null,\"lastSeenAt\":null,\"removedAt\":null}");
+
+        List<LifecycleRecord> records = source.read(file.toFile());
+
+        assertThat(records).extracting(LifecycleRecord::id).containsExactly("ep4");
+    }
+
     private Path writeFile(String... lines) throws IOException {
         Path file = tempDir.resolve("history.ndjson");
         Files.write(file, List.of(lines));