commit e17a351feb32304960f8e47ec18d979a784c1e68 parent 7b68f66437ad9e56f3c409b83559d3211278d9c4 Author: Michael Camilleri <[email protected]> Date: Mon, 11 May 2026 03:55:37 +0900 Add Crossmate version to puzzle data structures This commit adds a Crossmate version number (set to 1 if absent) for parsed puzzles so that it's possible to communicate to the system when it needs to reparse puzzle data. Co-Authored-By: Codex GPT 5.5 <[email protected]> Diffstat:
26 files changed, 187 insertions(+), 19 deletions(-)
diff --git a/Crossmake/Sources/Crossmake/main.swift b/Crossmake/Sources/Crossmake/main.swift @@ -640,6 +640,7 @@ func exportXD(state: PuzzleState, black: [Bool], slots: [Slot], options: Options let numbers = clueNumberGrid(black: black) var lines: [String] = [ "Title: \(options.title)", + "CmVer: 1", "Author: \(options.author)", "Publisher: Crossmake", "Date: \(ISO8601DateFormatter().string(from: Date()).prefix(10))", diff --git a/Crossmate/Models/CrossmateModel.xcdatamodeld/CrossmateModel.xcdatamodel/contents b/Crossmate/Models/CrossmateModel.xcdatamodeld/CrossmateModel.xcdatamodel/contents @@ -19,6 +19,8 @@ <attribute name="lastSeenOtherMoveAt" optional="YES" attributeType="Date" usesScalarValueType="NO"/> <attribute name="lastSyncedAt" optional="YES" attributeType="Date" usesScalarValueType="NO"/> <attribute name="latestOtherMoveAt" optional="YES" attributeType="Date" usesScalarValueType="NO"/> + <attribute name="puzzleResourceID" optional="YES" attributeType="String"/> + <attribute name="puzzleCmVersion" optional="YES" attributeType="Integer 64" defaultValueString="0" usesScalarValueType="YES"/> <attribute name="puzzleSource" attributeType="String"/> <attribute name="title" attributeType="String"/> <attribute name="updatedAt" attributeType="Date" usesScalarValueType="NO"/> diff --git a/Crossmate/Models/PuzzleCatalog.swift b/Crossmate/Models/PuzzleCatalog.swift @@ -7,6 +7,7 @@ struct PuzzleCatalog { let id: String // resource name (e.g. "sample") let title: String // parsed from the XD metadata let source: String // raw XD text + let cmVersion: Int // Crossmate version parser version } static func bundledPuzzles() -> [Entry] { @@ -17,6 +18,25 @@ struct PuzzleCatalog { puzzles(in: "Puzzles/Debug") } + static func source( + matchingResourceID resourceID: String?, + title: String? + ) -> Entry? { + let entries = bundledPuzzles() + debugPuzzles() + + if let resourceID { + return entries.first { $0.id == resourceID } + } else if let title { + return entries.first { $0.title == title } + } else { + return nil + } + } + + static func resourceID(matching source: String) -> String? { + (bundledPuzzles() + debugPuzzles()).first { $0.source == source }?.id + } + private static func puzzles(in subdirectory: String) -> [Entry] { guard let directoryURL = Bundle.main.resourceURL? .appendingPathComponent(subdirectory, isDirectory: true) else { @@ -33,7 +53,7 @@ struct PuzzleCatalog { let xd = try? XD.parse(source) else { return nil } - return Entry(id: name, title: xd.title ?? name, source: source) + return Entry(id: name, title: xd.title ?? name, source: source, cmVersion: xd.cmVersion) } .sorted { $0.id.localizedStandardCompare($1.id) == .orderedAscending } } diff --git a/Crossmate/Models/XD.swift b/Crossmate/Models/XD.swift @@ -4,11 +4,14 @@ import Foundation /// full specification. Supports just enough of the format to parse our /// bundled puzzles: metadata, grid (with rebus), and across/down clues. struct XD: Sendable { + static let currentCmVersion = 1 + let title: String? let publisher: String? let author: String? let copyright: String? let date: Date? + let cmVersion: Int let specialKind: Puzzle.Special? let width: Int let height: Int @@ -118,6 +121,7 @@ struct XD: Sendable { author: metadata["Author"], copyright: metadata["Copyright"], date: parseDateHeader(metadata["Date"]), + cmVersion: parseCmVersionHeader(metadata["CmVer"]), specialKind: specialKind, width: width, height: height, @@ -230,6 +234,15 @@ struct XD: Sendable { return Calendar(identifier: .gregorian).date(from: comps) } + /// Parses a Crossmate `CmVer:` header. Missing versions are version 1 + /// so legacy sources establish the baseline content version. + private static func parseCmVersionHeader(_ value: String?) -> Int { + guard let value else { return 1 } + let trimmed = value.trimmingCharacters(in: .whitespaces) + guard let version = Int(trimmed), version >= 1 else { return 1 } + return version + } + /// Parses a `Relatives:` header value into groups of cross-referenced /// clues. Groups are separated by `;`, tokens within a group by `,`, and /// each token is `{number}{A|D}` (e.g. `17A`, `57A`). This is a Crossmate diff --git a/Crossmate/Persistence/GameStore.swift b/Crossmate/Persistence/GameStore.swift @@ -336,12 +336,7 @@ final class GameStore { guard let entity = try context.fetch(request).first else { throw LoadError.gameNotFound } - guard let source = entity.puzzleSource else { - throw LoadError.persistedSourceMissing - } - - let xd = try XD.parse(source) - let puzzle = Puzzle(xd: xd) + let puzzle = try preparePuzzleForLoad(from: entity) let game = Game(puzzle: puzzle) restore(game: game, from: entity) @@ -357,13 +352,32 @@ final class GameStore { // MARK: - Duplicate detection - /// Returns the ID of an existing game whose stored `puzzleSource` - /// matches `source` exactly, or nil if no such game exists. + /// Returns the ID of an existing game for the same source. Exact source + /// matches win, then catalog resource ID/title matches catch older stored + /// copies of a packaged puzzle. func findGameID(matching source: String) -> UUID? { let request = NSFetchRequest<GameEntity>(entityName: "GameEntity") request.predicate = NSPredicate(format: "puzzleSource == %@", source) request.fetchLimit = 1 - return (try? context.fetch(request).first?.id) + if let exact = try? context.fetch(request).first?.id { + return exact + } + + guard let xd = try? XD.parse(source) else { return nil } + let resourceID = PuzzleCatalog.resourceID(matching: source) + let fallback = NSFetchRequest<GameEntity>(entityName: "GameEntity") + if let resourceID { + fallback.predicate = NSPredicate(format: "puzzleResourceID == %@", resourceID) + fallback.fetchLimit = 1 + if let match = try? context.fetch(fallback).first?.id { + return match + } + } + + guard resourceID != nil, let title = xd.title else { return nil } + fallback.predicate = NSPredicate(format: "title == %@", title) + fallback.fetchLimit = 1 + return (try? context.fetch(fallback).first?.id) } /// Returns joined CloudKit-share games that have a usable puzzle payload. @@ -391,6 +405,8 @@ final class GameStore { entity.id = gameID entity.title = puzzle.title entity.puzzleSource = source + entity.puzzleCmVersion = Int64(XD.currentCmVersion) + entity.puzzleResourceID = PuzzleCatalog.resourceID(matching: source) entity.createdAt = now entity.updatedAt = now entity.ckRecordName = "game-\(gameID.uuidString)" @@ -499,11 +515,7 @@ final class GameStore { if let existing = try fetchCurrentEntity() { entity = existing - guard let source = existing.puzzleSource else { - throw LoadError.persistedSourceMissing - } - let xd = try XD.parse(source) - puzzle = Puzzle(xd: xd) + puzzle = try preparePuzzleForLoad(from: existing) } else { (entity, puzzle) = try seedFromSample() } @@ -554,6 +566,8 @@ final class GameStore { entity.id = gameID entity.title = puzzle.title entity.puzzleSource = source + entity.puzzleCmVersion = Int64(XD.currentCmVersion) + entity.puzzleResourceID = PuzzleCatalog.resourceID(matching: source) entity.createdAt = now entity.updatedAt = now entity.ckRecordName = "game-\(gameID.uuidString)" @@ -566,6 +580,41 @@ final class GameStore { return (entity, puzzle) } + private func preparePuzzleForLoad(from entity: GameEntity) throws -> Puzzle { + guard let source = entity.puzzleSource else { + throw LoadError.persistedSourceMissing + } + + let currentVersion = Int64(XD.currentCmVersion) + if entity.puzzleCmVersion != currentVersion { + let catalogSource = PuzzleCatalog.source( + matchingResourceID: entity.puzzleResourceID, + title: try? XD.parse(source).title + ) + let nextSource = catalogSource?.source ?? source + let nextXD = try XD.parse(nextSource) + let puzzle = Puzzle(xd: nextXD) + entity.title = puzzle.title + entity.puzzleSource = nextSource + entity.puzzleCmVersion = currentVersion + if let catalogSource { + entity.puzzleResourceID = catalogSource.id + } else if entity.puzzleResourceID == nil { + entity.puzzleResourceID = PuzzleCatalog.resourceID(matching: nextSource) + } + entity.populateCachedSummaryFields(from: puzzle) + try context.save() + return puzzle + } + + if entity.puzzleResourceID == nil { + entity.puzzleResourceID = PuzzleCatalog.resourceID(matching: source) + if context.hasChanges { try context.save() } + } + + return Puzzle(xd: try XD.parse(source)) + } + private func restore(game: Game, from entity: GameEntity) { let movesRequest = NSFetchRequest<MovesEntity>(entityName: "MovesEntity") movesRequest.predicate = NSPredicate(format: "game == %@", entity) diff --git a/Crossmate/Persistence/PersistenceController.swift b/Crossmate/Persistence/PersistenceController.swift @@ -43,9 +43,9 @@ final class PersistenceController { } } - /// One-shot pass for `GameEntity` rows created before - /// `populateCachedSummaryFields` was wired into the creation paths. Runs - /// off the main thread, no-ops on every subsequent launch. + /// One-shot pass for `GameEntity` rows created before cached summary + /// fields were wired into the creation paths. Runs off the main thread, + /// no-ops on every subsequent launch. private func backfillCachedSummaryFields() { let bg = container.newBackgroundContext() bg.perform { diff --git a/Crossmate/Services/NYTToXDConverter.swift b/Crossmate/Services/NYTToXDConverter.swift @@ -183,6 +183,7 @@ enum NYTToXDConverter { // Metadata section var metadata: [String] = [] metadata.append("Title: \(title(forPublicationDate: publicationDate))") + metadata.append("CmVer: \(XD.currentCmVersion)") metadata.append("Publisher: New York Times") if !publicationDate.isEmpty { metadata.append("Date: \(publicationDate)") diff --git a/Crossmate/Services/PUZToXDConverter.swift b/Crossmate/Services/PUZToXDConverter.swift @@ -88,6 +88,7 @@ enum PUZToXDConverter { var metadata: [String] = [] if !title.isEmpty { metadata.append("Title: \(title)") } + metadata.append("CmVer: \(XD.currentCmVersion)") if !author.isEmpty { metadata.append("Author: \(author)") } if !copyright.isEmpty { metadata.append("Copyright: \(copyright)") } if !rebusEntries.isEmpty { diff --git a/Crossmate/Sync/RecordSerializer.swift b/Crossmate/Sync/RecordSerializer.swift @@ -364,6 +364,7 @@ enum RecordSerializer { let source = try? String(contentsOf: fileURL, encoding: .utf8) { entity.puzzleSource = source if let xd = try? XD.parse(source) { + entity.puzzleCmVersion = Int64(XD.currentCmVersion) entity.populateCachedSummaryFields(from: Puzzle(xd: xd)) } } diff --git a/Puzzles/Bundled/Crossmate-0001.xd b/Puzzles/Bundled/Crossmate-0001.xd @@ -1,4 +1,5 @@ Title: Crossmake #1 +CmVer: 1 Author: Crossmake Publisher: Crossmake Date: 2026-04-29 diff --git a/Puzzles/Bundled/Crossmate-0002.xd b/Puzzles/Bundled/Crossmate-0002.xd @@ -1,4 +1,5 @@ Title: Crossmake #2 +CmVer: 1 Author: Crossmake Publisher: Crossmake Date: 2026-04-29 diff --git a/Puzzles/Bundled/Crossmate-0003.xd b/Puzzles/Bundled/Crossmate-0003.xd @@ -1,4 +1,5 @@ Title: Crossmake #3 +CmVer: 1 Author: Crossmake Publisher: Crossmake Date: 2026-04-29 diff --git a/Puzzles/Bundled/Crossmate-0004.xd b/Puzzles/Bundled/Crossmate-0004.xd @@ -1,4 +1,5 @@ Title: Crossmake #4 +CmVer: 1 Author: Crossmake Publisher: Crossmake Date: 2026-04-29 diff --git a/Puzzles/Bundled/Crossmate-0005.xd b/Puzzles/Bundled/Crossmate-0005.xd @@ -1,4 +1,5 @@ Title: Crossmake #5 +CmVer: 1 Author: Crossmake Publisher: Crossmake Date: 2026-04-29 diff --git a/Puzzles/Bundled/Crossmate-0006.xd b/Puzzles/Bundled/Crossmate-0006.xd @@ -1,4 +1,5 @@ Title: Crossmake #6 +CmVer: 1 Author: Crossmake Publisher: Crossmake Date: 2026-04-29 diff --git a/Puzzles/Bundled/Crossmate-0007.xd b/Puzzles/Bundled/Crossmate-0007.xd @@ -1,4 +1,5 @@ Title: Crossmake #7 +CmVer: 1 Author: Crossmake Publisher: Crossmake Date: 2026-04-29 diff --git a/Puzzles/Bundled/Crossmate-0008.xd b/Puzzles/Bundled/Crossmate-0008.xd @@ -1,4 +1,5 @@ Title: Crossmake #8 +CmVer: 1 Author: Crossmake Publisher: Crossmake Date: 2026-04-29 diff --git a/Puzzles/Bundled/Crossmate-0009.xd b/Puzzles/Bundled/Crossmate-0009.xd @@ -1,4 +1,5 @@ Title: Crossmake #9 +CmVer: 1 Author: Crossmake Publisher: Crossmake Date: 2026-04-29 diff --git a/Puzzles/Bundled/Crossmate-0010.xd b/Puzzles/Bundled/Crossmate-0010.xd @@ -1,4 +1,5 @@ Title: Crossmake #10 +CmVer: 1 Author: Crossmake Publisher: Crossmake Date: 2026-04-29 diff --git a/Puzzles/Debug/garden.xd b/Puzzles/Debug/garden.xd @@ -1,4 +1,5 @@ Title: Garden Party +CmVer: 1 Author: Crossmate Copyright: Public domain test puzzle diff --git a/Puzzles/Debug/morning.xd b/Puzzles/Debug/morning.xd @@ -1,4 +1,5 @@ Title: Morning Routine +CmVer: 1 Author: Crossmate Copyright: Public domain test puzzle diff --git a/Puzzles/Debug/sample.xd b/Puzzles/Debug/sample.xd @@ -1,4 +1,5 @@ Title: Crossmate Demo +CmVer: 1 Author: Crossmate Copyright: Public domain test puzzle diff --git a/Tests/Unit/GameStoreUnseenMovesTests.swift b/Tests/Unit/GameStoreUnseenMovesTests.swift @@ -141,4 +141,24 @@ struct GameStoreUnseenMovesTests { let summary = try #require(GameSummary(entity: entity)) #expect(!summary.hasUnseenOtherMoves) } + + @Test("Opening a stale CmVer game reparses source and records current CmVer") + func openingStaleCmVerGameReparsesSource() throws { + let persistence = makeTestPersistence() + let store = makeTestStore(persistence: persistence) + let ctx = persistence.viewContext + let (entity, _) = try makeSharedGame(in: ctx) + entity.puzzleCmVersion = 0 + entity.gridWidth = 0 + entity.gridHeight = 0 + entity.blockMask = nil + try ctx.save() + + _ = try store.loadGame(id: entity.id!) + + #expect(entity.puzzleCmVersion == Int64(XD.currentCmVersion)) + #expect(entity.gridWidth == 3) + #expect(entity.gridHeight == 3) + #expect(entity.blockMask?.count == 9) + } } diff --git a/Tests/Unit/MovesUpdaterTests.swift b/Tests/Unit/MovesUpdaterTests.swift @@ -80,6 +80,18 @@ struct MovesUpdaterTests { return try MovesCodec.decode(data) } + private func waitForFlushCount( + _ expected: Int, + capture: Capture, + timeout: Duration = .seconds(1) + ) async throws { + let deadline = ContinuousClock.now.advanced(by: timeout) + while await capture.flushCount != expected, + ContinuousClock.now < deadline { + try await Task.sleep(for: .milliseconds(20)) + } + } + @Test("Same-cell enqueues coalesce; latest value lands in MovesEntity") func coalescesSameCell() async throws { let (persistence, gameID) = try makePersistenceWithGame() @@ -131,7 +143,7 @@ struct MovesUpdaterTests { await updater.enqueue(gameID: gameID, row: 0, col: 0, letter: "A", markKind: 0, checkedWrong: false, authorID: "alice") await updater.enqueue(gameID: gameID, row: 0, col: 0, letter: "B", markKind: 0, checkedWrong: false, authorID: "alice") - try await Task.sleep(for: .milliseconds(200)) + try await waitForFlushCount(1, capture: capture) #expect(await capture.flushCount == 1) let cells = try decodedCells(gameID: gameID, persistence: persistence) diff --git a/Tests/Unit/PuzzleCatalogTests.swift b/Tests/Unit/PuzzleCatalogTests.swift @@ -11,6 +11,7 @@ struct PuzzleCatalogTests { #expect(puzzles.count == 10) #expect(puzzles.map(\.title).contains("Crossmake #1")) #expect(puzzles.map(\.title).contains("Crossmake #10")) + #expect(puzzles.allSatisfy { $0.cmVersion == XD.currentCmVersion }) #expect(puzzles.map(\.id) == [ "Crossmate-0001", "Crossmate-0002", @@ -30,5 +31,6 @@ struct PuzzleCatalogTests { let puzzles = PuzzleCatalog.debugPuzzles() #expect(puzzles.count == 3) + #expect(puzzles.allSatisfy { $0.cmVersion == XD.currentCmVersion }) } } diff --git a/Tests/Unit/XDAcceptTests.swift b/Tests/Unit/XDAcceptTests.swift @@ -6,6 +6,39 @@ import Testing @Suite("XD Accept metadata") @MainActor struct XDAcceptTests { + @Test("Missing CmVer defaults to one") + func missingCmVerDefaultsToOne() throws { + let xd = try XD.parse(""" + Title: Versionless + + + A + + + A1. Letter ~ A + D1. Letter ~ A + """) + + #expect(xd.cmVersion == 1) + } + + @Test("Explicit positive CmVer is parsed") + func explicitCmVerIsParsed() throws { + let xd = try XD.parse(""" + Title: Versioned + CmVer: 3 + + + A + + + A1. Letter ~ A + D1. Letter ~ A + """) + + #expect(xd.cmVersion == 3) + } + @Test("Clue metadata is parsed generically") func clueMetadataParsesGenerically() throws { let source = """