crossmate

NYTToXDConverter.swift (19624B)

---

 import Foundation
 
 /// Converts NYT puzzle JSON (from `/v6/puzzle/daily/{date}.json`) to `.xd` format.
 enum NYTToXDConverter {
     struct ConversionError: LocalizedError {
         let message: String
         var errorDescription: String? { message }
     }
 
     /// Converts raw JSON data from the NYT puzzle endpoint to an `.xd` source string.
     static func convert(jsonData: Data) throws -> String {
         guard let root = try JSONSerialization.jsonObject(with: jsonData) as? [String: Any] else {
             throw ConversionError(message: "Invalid JSON root.")
         }
 
         // -- Metadata --
 
         let publicationDate = root["publicationDate"] as? String ?? ""
         let constructors = root["constructors"] as? [String] ?? []
         let editor = root["editor"] as? String
         let copyright = root["copyright"] as? String
 
         guard let bodyArray = root["body"] as? [[String: Any]],
               let body = bodyArray.first else {
             throw ConversionError(message: "Missing body in puzzle JSON.")
         }
 
         guard let dimensions = body["dimensions"] as? [String: Int],
               let width = dimensions["width"],
               let height = dimensions["height"] else {
             throw ConversionError(message: "Missing dimensions.")
         }
 
         guard let cells = body["cells"] as? [Any] else {
             throw ConversionError(message: "Missing cells.")
         }
 
         guard cells.count == width * height else {
             throw ConversionError(message: "Cell count (\(cells.count)) does not match dimensions (\(width)x\(height)).")
         }
 
         guard let clues = body["clues"] as? [[String: Any]] else {
             throw ConversionError(message: "Missing clues.")
         }
 
         // -- Parse cells into answers --
 
         // Each cell is either an empty dict (block) or a dict with "answer", "type", etc.
         var answers: [String?] = []  // nil = block, String = answer
         var acceptedAnswersByCellIndex: [Int: [String]] = [:]
         var nextRebusKey: Character = "1"
 
         for (index, cell) in cells.enumerated() {
             guard let dict = cell as? [String: Any], !dict.isEmpty else {
                 answers.append(nil)
                 continue
             }
 
             let answer = dict["answer"] as? String ?? ""
             if answer.isEmpty {
                 answers.append(nil)
             } else {
                 answers.append(answer)
             }
 
             if let moreAnswers = dict["moreAnswers"] as? [String: Any],
                let valid = moreAnswers["valid"] as? [String] {
                 let cleaned = valid.filter { !$0.isEmpty && $0 != answer }
                 if !cleaned.isEmpty {
                     acceptedAnswersByCellIndex[index] = cleaned
                 }
             }
         }
 
         // -- Build rebus header if needed --
 
         // Check for multi-character answers.
         var rebusEntries: [(key: Character, value: String)] = []
         var rebusLookup: [String: Character] = [:]
 
         for answer in answers {
             guard let answer, answer.count > 1 else { continue }
             if rebusLookup[answer] == nil {
                 let key = nextRebusKey
                 rebusLookup[answer] = key
                 rebusEntries.append((key: key, value: answer))
                 // Advance to next digit/letter for rebus key
                 nextRebusKey = Character(UnicodeScalar(nextRebusKey.asciiValue! + 1))
             }
         }
 
         // -- Find special (shaded/circled) cells from the SVG --
 
         let (specialCells, specialKind) = specialCellInfo(body: body)
 
         // -- Build grid lines --
 
         var gridLines: [String] = []
         for row in 0..<height {
             var line = ""
             for col in 0..<width {
                 let index = row * width + col
                 guard let answer = answers[index] else {
                     line += "#"
                     continue
                 }
                 let isSpecial = specialCells.contains(index)
                 if answer.count > 1 {
                     // Rebus: use the placeholder character. Lowercase marking
                     // only applies to single-letter cells per the .xd spec, so
                     // shading on a rebus cell would be lost here — no puzzle
                     // we've seen combines the two.
                     line += String(rebusLookup[answer]!)
                 } else {
                     line += isSpecial ? answer.lowercased() : answer
                 }
             }
             gridLines.append(line)
         }
 
         // -- Build clue lines --
 
         // Sort clues: Across first, then Down; within each group, by label number.
         let sortedClues = clues.sorted { a, b in
             let dirA = (a["direction"] as? String) ?? ""
             let dirB = (b["direction"] as? String) ?? ""
             if dirA != dirB { return dirA == "Across" }
             let labelA = intValue(a["label"]) ?? 0
             let labelB = intValue(b["label"]) ?? 0
             return labelA < labelB
         }
 
         var acrossClueLines: [String] = []
         var downClueLines: [String] = []
 
         for clue in sortedClues {
             let direction = clue["direction"] as? String ?? ""
             let label = intValue(clue["label"]) ?? 0
 
             // Extract clue text from the nested structure:
             // "text": [{"plain": "Clue text"}]
             let clueText: String
             if let textArray = clue["text"] as? [[String: Any]],
                let firstText = textArray.first,
                let plain = firstText["plain"] as? String {
                 clueText = plain
             } else {
                 clueText = ""
             }
 
             // Build answer from cell indices
             let cellIndices = clue["cells"] as? [Int] ?? []
             let answerStr = cellIndices.compactMap { answers[$0] }.joined()
 
             let prefix = direction == "Across" ? "A" : "D"
             let line = "\(prefix)\(label). \(clueText) ~ \(answerStr)"
             let acceptLine: String?
             let acceptedAnswers = acceptedAnswerVariants(
                 cellIndices: cellIndices,
                 answers: answers,
                 acceptedAnswersByCellIndex: acceptedAnswersByCellIndex
             )
             if acceptedAnswers.isEmpty {
                 acceptLine = nil
             } else {
                 let escaped = acceptedAnswers.map(escapeAcceptToken).joined(separator: " ")
                 acceptLine = "\(prefix)\(label) ^Accept: \(escaped)"
             }
 
             if direction == "Across" {
                 acrossClueLines.append(line)
                 if let acceptLine { acrossClueLines.append(acceptLine) }
             } else {
                 downClueLines.append(line)
                 if let acceptLine { downClueLines.append(acceptLine) }
             }
         }
 
         // -- Assemble .xd source --
 
         var sections: [String] = []
 
         // 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)")
         }
         if !constructors.isEmpty {
             metadata.append("Author: \(constructors.joined(separator: ", "))")
         }
         if let editor {
             metadata.append("Editor: \(editor)")
         }
         if let copyright {
             metadata.append("Copyright: \(copyright)")
         }
 
         if !rebusEntries.isEmpty {
             let rebusStr = rebusEntries.map { "\($0.key)=\($0.value)" }.joined(separator: " ")
             metadata.append("Rebus: \(rebusStr)")
         }
 
         if !specialCells.isEmpty, let specialKind {
             metadata.append("Special: \(specialKind)")
         }
 
         let relatives = buildRelativeGroups(clues: clues)
         if !relatives.isEmpty {
             let joined = relatives
                 .map { $0.joined(separator: ",") }
                 .joined(separator: "; ")
             metadata.append("Relatives: \(joined)")
         }
 
         sections.append(metadata.joined(separator: "\n"))
 
         // Grid section
         sections.append(gridLines.joined(separator: "\n"))
 
         // Clue sections (across then down, separated by blank line)
         let allClueLines = acrossClueLines + [""] + downClueLines
         sections.append(allClueLines.joined(separator: "\n"))
 
         // The .xd parser splits sections on two or more consecutive blank lines,
         // so we need two blank lines (three newlines) between sections.
         return sections.joined(separator: "\n\n\n")
     }
 
     private static func acceptedAnswerVariants(
         cellIndices: [Int],
         answers: [String?],
         acceptedAnswersByCellIndex: [Int: [String]]
     ) -> [String] {
         var variants: [String] = []
         var seen = Set<String>()
         let canonicalParts = cellIndices.map { answers.indices.contains($0) ? answers[$0] ?? "" : "" }
         let canonicalAnswer = canonicalParts.joined()
 
         for (partIndex, cellIndex) in cellIndices.enumerated() {
             guard let accepted = acceptedAnswersByCellIndex[cellIndex] else { continue }
             for value in accepted {
                 var parts = canonicalParts
                 parts[partIndex] = value
                 let variant = parts.joined()
                 guard variant != canonicalAnswer, seen.insert(variant).inserted else { continue }
                 variants.append(variant)
             }
         }
 
         return variants
     }
 
     private static func escapeAcceptToken(_ token: String) -> String {
         var escaped = ""
         for ch in token {
             if ch == "\\" || ch.isWhitespace {
                 escaped.append("\\")
             }
             escaped.append(ch)
         }
         return escaped
     }
 
     private static func title(forPublicationDate publicationDate: String) -> String {
         guard let date = date(fromPublicationDate: publicationDate) else {
             return "NYT Crossword"
         }
 
         let formatter = DateFormatter()
         formatter.calendar = Calendar(identifier: .gregorian)
         formatter.locale = Locale(identifier: "en_US_POSIX")
         formatter.timeZone = TimeZone(identifier: "America/New_York")
         formatter.dateFormat = "EEEE"
         return "\(formatter.string(from: date)) Crossword"
     }
 
     private static func date(fromPublicationDate publicationDate: String) -> Date? {
         let trimmed = publicationDate.trimmingCharacters(in: .whitespaces)
         guard let match = trimmed.firstMatch(of: /^(\d{4})-(\d{2})-(\d{2})$/),
               let year = Int(match.1),
               let month = Int(match.2),
               let day = Int(match.3)
         else { return nil }
 
         var calendar = Calendar(identifier: .gregorian)
         calendar.timeZone = TimeZone(identifier: "America/New_York") ?? .gmt
         var comps = DateComponents()
         comps.calendar = calendar
         comps.timeZone = calendar.timeZone
         comps.year = year
         comps.month = month
         comps.day = day
         return calendar.date(from: comps)
     }
 
     /// Themer/revealer groups: the structured `relatives` field plus
     /// italics-flagged theme answers. These are the connections the
     /// constructor did *not* surface in clue text — typically the trick
     /// underlying a theme — so they're suitable for catalog/analysis but
     /// should not drive any in-grid highlighting that would spoil the solve.
     /// Cross-references that live in clue prose ("See 11-Down") are derived
     /// at puzzle-load time in `Puzzle.init` instead.
     private static func buildRelativeGroups(clues: [[String: Any]]) -> [[String]] {
         var groups = buildRelatives(clues: clues)
         groups.append(contentsOf: buildFormattedClueGroups(clues: clues))
         var seen = Set<Set<String>>()
         return groups.filter { group in
             let key = Set(group)
             guard !key.isEmpty, !seen.contains(key) else { return false }
             seen.insert(key)
             return true
         }
     }
 
     /// Builds groups of cross-referenced clues from the v6 per-clue
     /// `relatives` arrays. Two rules admit a group, everything else is
     /// discarded:
     ///
     /// 1. **Revealer** — a clue with ≥2 relatives defines a group consisting
     ///    of itself plus every clue it references. The revealer's list is
     ///    treated as canonical.
     /// 2. **Mutual pair** — two clues that each list the other as their sole
     ///    relative form a group of two (the classic "See 14-Across" pattern).
     ///
     /// Single-direction 1-relative edges (where A references B but B does
     /// not reference A back) are dropped. This guards against NYT data
     /// errors where a leaf clue points at the wrong revealer.
     private static func buildRelatives(clues: [[String: Any]]) -> [[String]] {
         // Extract each clue's (label, direction) and relatives array.
         var tokens: [String?] = []
         var relativeIndices: [[Int]] = []
         tokens.reserveCapacity(clues.count)
         relativeIndices.reserveCapacity(clues.count)
         for clue in clues {
             let direction = clue["direction"] as? String ?? ""
             let label = intValue(clue["label"]) ?? 0
             if label > 0, direction == "Across" || direction == "Down" {
                 tokens.append("\(label)\(direction == "Across" ? "A" : "D")")
             } else {
                 tokens.append(nil)
             }
             let raw = clue["relatives"] as? [Int] ?? []
             let cleaned = Array(Set(raw.filter { $0 >= 0 && $0 < clues.count }))
             relativeIndices.append(cleaned)
         }
 
         var groups: [[String]] = []
         var seen = Set<Set<Int>>()
 
         func emit(_ members: Set<Int>) {
             guard members.count >= 2, !seen.contains(members) else { return }
             seen.insert(members)
             let sorted = members.sorted { a, b in
                 // Order by (number, direction-is-across-first). Extract from
                 // the stored token; fallback to index if a token is missing.
                 guard let ta = tokens[a], let tb = tokens[b] else { return a < b }
                 let (na, da) = (Int(ta.dropLast()) ?? 0, ta.last!)
                 let (nb, db) = (Int(tb.dropLast()) ?? 0, tb.last!)
                 if na != nb { return na < nb }
                 return da == "A" && db == "D"
             }
             let toks = sorted.compactMap { tokens[$0] }
             if toks.count >= 2 { groups.append(toks) }
         }
 
         // Rule 1: revealers.
         for (i, refs) in relativeIndices.enumerated() where refs.count >= 2 {
             var members = Set<Int>()
             members.insert(i)
             for r in refs { members.insert(r) }
             emit(members)
         }
 
         // Rule 2: mutual pairs. Only consider clues with exactly one relative
         // — revealer-formed groups already cover the multi-relative cases.
         for (i, refs) in relativeIndices.enumerated() where refs.count == 1 {
             let j = refs[0]
             guard j != i, relativeIndices.indices.contains(j) else { continue }
             if relativeIndices[j] == [i] {
                 emit(Set([i, j]))
             }
         }
 
         return groups
     }
 
     /// NYT marks some theme clues by supplying formatted clue text, commonly
     /// `<i>...</i>`, without adding `relatives`. Group all such clue refs so
     /// their answer cells can be highlighted by Crossmate's thematic mask.
     private static func buildFormattedClueGroups(clues: [[String: Any]]) -> [[String]] {
         let tokens = clues.compactMap { clue -> String? in
             guard clueHasFormattedText(clue) else { return nil }
             return clueToken(clue)
         }
         return tokens.isEmpty ? [] : [tokens]
     }
 
     private static func clueHasFormattedText(_ clue: [String: Any]) -> Bool {
         guard let textArray = clue["text"] as? [[String: Any]] else { return false }
         return textArray.contains { textPart in
             guard let formatted = textPart["formatted"] as? String else { return false }
             return !formatted.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
         }
     }
 
     private static func clueToken(_ clue: [String: Any]) -> String? {
         let direction = clue["direction"] as? String ?? ""
         let label = intValue(clue["label"]) ?? 0
         guard label > 0, direction == "Across" || direction == "Down" else { return nil }
         return "\(label)\(direction == "Across" ? "A" : "D")"
     }
 
     /// Walks the structured SVG tree under `body.SVG` to find cells that
     /// carry a theme marker. The cells group is a `<g data-group="cells">`
     /// whose children are per-cell `<g>` nodes in `body.cells` order — so the
     /// child's array index is the cell index. Two markers are recognised:
     ///
     /// * Shaded cells — the cell's `<rect>` background has `fill="lightgray"`.
     /// * Circled cells — the cell group contains a `<circle>` element.
     ///
     /// The `.xd` format only supports one `Special:` kind per puzzle. If a
     /// grid mixes both (not seen in the wild yet), circles take precedence
     /// since they're the more visually distinct marker.
     private static func specialCellInfo(body: [String: Any]) -> (indices: Set<Int>, kind: String?) {
         guard let svg = body["SVG"] as? [String: Any],
               let topChildren = svg["children"] as? [[String: Any]] else {
             return ([], nil)
         }
 
         let cellsGroup = topChildren.first { node in
             guard (node["name"] as? String) == "g",
                   let attrs = node["attributes"] as? [[String: Any]] else {
                 return false
             }
             return attrs.contains { attr in
                 (attr["name"] as? String) == "data-group"
                     && (attr["value"] as? String) == "cells"
             }
         }
 
         guard let cellsGroup,
               let cellGroups = cellsGroup["children"] as? [[String: Any]] else {
             return ([], nil)
         }
 
         var shaded: Set<Int> = []
         var circled: Set<Int> = []
         for (index, cellGroup) in cellGroups.enumerated() {
             guard let inner = cellGroup["children"] as? [[String: Any]] else {
                 continue
             }
             if let rect = inner.first,
                (rect["name"] as? String) == "rect",
                let attrs = rect["attributes"] as? [[String: Any]] {
                 let fill = attrs.first {
                     ($0["name"] as? String) == "fill"
                 }?["value"] as? String
                 if fill == "lightgray" {
                     shaded.insert(index)
                 }
             }
             if inner.contains(where: { ($0["name"] as? String) == "circle" }) {
                 circled.insert(index)
             }
         }
 
         if !circled.isEmpty {
             return (circled.union(shaded), "circle")
         }
         if !shaded.isEmpty {
             return (shaded, "shaded")
         }
         return ([], nil)
     }
 
     /// Extracts an Int from a JSON value that may be NSNumber, Int, or Double.
     private static func intValue(_ value: Any?) -> Int? {
         if let n = value as? Int { return n }
         if let s = value as? String { return Int(s) }
         if let n = value as? NSNumber { return n.intValue }
         if let n = value as? Double { return Int(n) }
         return nil
     }
 }