Support diffing for RenderNode (#696)

These changes implement support to diff any two RenderNode objects, across all their properties, and generate a list of JSON Patches to go from the first RenderNode to the second one. To achieve this:

* A new RenderJSONDiffable protocol is defined to ensure similar object types can be diffed. RenderJSONDiffable conformance requires the object to implement difference(from:at:) and optionally isSimilar(to:) methods. This is done for all RenderNode object types and for common built-in types used with JSON.
* DifferenceBuilder is defined to help abstracting away the different difference methods. It collects differences between two objects and handles the JSON paths for those differences using addDifferences(atKeyPath:forKey:) method.
* The following content is supported for diffing yet:
  * Language-specific overrides
  * Tutorials

rdar://105186012

Co-authored-by: Maya Epps <[email protected]>

Author: raul-ramirezl

Sources/SwiftDocC/Infrastructure/Communication/Foundation/JSON.swift

@@ -138,3 +138,34 @@ extension JSON {
     }
 
 }
+
+extension JSON {
+    /// An integer coding key.
+    struct IntegerKey: CodingKey {
+        var intValue: Int?
+        var stringValue: String
+        
+        init(_ value: Int) {
+            self.intValue = value
+            self.stringValue = value.description
+        }
+        
+        init(_ value: String) {
+            self.intValue = nil
+            self.stringValue = value
+        }
+        
+        init?(intValue: Int) {
+            self.init(intValue)
+        }
+        
+        init?(stringValue: String) {
+            guard let intValue = Int(stringValue) else {
+                return nil
+            }
+            
+            self.intValue = intValue
+            self.stringValue = stringValue
+        }
+    }
+}

Sources/SwiftDocC/Model/Identifier.swift

@@ -514,6 +514,21 @@ extension ResolvedTopicReference {
     }
 }
 
+extension ResolvedTopicReference: RenderJSONDiffable {
+    /// Returns the differences between this ResolvedTopicReference and the given one.
+    func difference(from other: ResolvedTopicReference, at path: CodablePath) -> JSONPatchDifferences {
+        var diffBuilder = DifferenceBuilder(current: self, other: other, basePath: path)
+
+        // The only part of the URL that is encoded to RenderJSON is the absolute string.
+        diffBuilder.addDifferences(atKeyPath: \.url.absoluteString, forKey: CodingKeys.url)
+        
+        // The only part of the source language that is encoded to RenderJSON is the id.
+        diffBuilder.addDifferences(atKeyPath: \.sourceLanguage.id, forKey: CodingKeys.interfaceLanguage)
+        
+        return diffBuilder.differences
+    }
+}
+
 /// An unresolved reference to a documentation node.
 ///
 /// You can create unresolved references from partial information if that information can be derived from the enclosing context when the

Sources/SwiftDocC/Model/Rendering/Content/RenderInlineContent.swift

@@ -217,3 +217,16 @@ extension Sequence where Element == RenderInlineContent {
         return map { $0.plainText }.joined()
     }
 }
+
+// Diffable conformance
+extension RenderInlineContent: RenderJSONDiffable {
+    /// Returns the differences between this RenderInlineContent and the given one.
+    func difference(from other: RenderInlineContent, at path: CodablePath) -> JSONPatchDifferences {
+        var diffBuilder = DifferenceBuilder(current: self, other: other, basePath: path)
+
+        diffBuilder.addDifferences(atKeyPath: \.type, forKey: CodingKeys.type)
+        diffBuilder.addDifferences(atKeyPath: \.plainText, forKey: CodingKeys.text)
+
+        return diffBuilder.differences
+    }
+}

Sources/SwiftDocC/Model/Rendering/Diffing/AnyRenderReference.swift

@@ -0,0 +1,95 @@
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 2021-2023 Apple Inc. and the Swift project authors
+ Licensed under Apache License v2.0 with Runtime Library Exception
+
+ See https://swift.org/LICENSE.txt for license information
+ See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/
+
+/// A RenderReference value that can be diffed.
+///
+/// An `AnyRenderReference` value forwards difference operations to the underlying base type, which implement the difference differently.
+struct AnyRenderReference: Encodable, Equatable, RenderJSONDiffable {
+    var value: RenderReference & Codable
+    
+    init(_ value: RenderReference & Codable) {
+        self.value = value
+    }
+    
+    func encode(to encoder: Encoder) throws {
+        try value.encode(to: encoder)
+    }
+    
+    /// Forwards the difference methods on to the correct concrete type.
+    func difference(from other: AnyRenderReference, at path: CodablePath) -> JSONPatchDifferences {
+        switch (self.value.type, other.value.type) {
+            
+        // MARK: References
+            
+        case (.file, .file):
+            return (value as! FileReference).difference(from: (other.value as! FileReference), at: path)
+        case (.fileType, .fileType):
+            return (value as! FileTypeReference).difference(from: (other.value as! FileTypeReference), at: path)
+        case (.image, .image):
+            return (value as! ImageReference).difference(from: (other.value as! ImageReference), at: path)
+        case (.link, .link):
+            return (value as! LinkReference).difference(from: (other.value as! LinkReference), at: path)
+        case (.section, .section), (.topic, .topic):
+            return (value as! TopicRenderReference).difference(from: (other.value as! TopicRenderReference), at: path)
+        case (.unresolvable, .unresolvable):
+            return (value as! UnresolvedRenderReference).difference(from: (other.value as! UnresolvedRenderReference), at: path)
+        case (.video, .video):
+            return (value as! VideoReference).difference(from: (other.value as! VideoReference), at: path)
+            
+        // MARK: Tutorial References
+            
+        case (.download, .download):
+            return (value as! DownloadReference).difference(from: (other.value as! DownloadReference), at: path)
+        case (.xcodeRequirement, .xcodeRequirement):
+            return (value as! XcodeRequirementReference).difference(from: (other.value as! XcodeRequirementReference), at: path)
+            
+        default:
+            assertionFailure("Case diffing \(value) with \(other.value) is not implemented.")
+            return []
+        }
+    }
+
+    static func == (lhs: AnyRenderReference, rhs: AnyRenderReference) -> Bool {
+        switch (lhs.value.type, rhs.value.type) {
+            
+        // MARK: References
+          
+        case (.file, .file):
+            return (lhs.value as! FileReference) == (rhs.value as! FileReference)
+        case (.fileType, .fileType):
+            return (lhs.value as! FileTypeReference) == (rhs.value as! FileTypeReference)
+        case (.image, .image):
+            return (lhs.value as! ImageReference) == (rhs.value as! ImageReference)
+        case (.link, .link):
+            return (lhs.value as! LinkReference) == (rhs.value as! LinkReference)
+        case (.section, .section), (.topic, .topic):
+            return (lhs.value as! TopicRenderReference) == (rhs.value as! TopicRenderReference)
+        case (.unresolvable, .unresolvable):
+            return (lhs.value as! UnresolvedRenderReference) == (rhs.value as! UnresolvedRenderReference)
+        case (.video, .video):
+            return (lhs.value as! VideoReference) == (rhs.value as! VideoReference)
+        
+        // MARK: Tutorial References
+            
+        case (.download, .download):
+            return (lhs.value as! DownloadReference) == (rhs.value as! DownloadReference)
+        case (.xcodeRequirement, .xcodeRequirement):
+            return (lhs.value as! XcodeRequirementReference) == (rhs.value as! XcodeRequirementReference)
+        
+        default:
+            assertionFailure("Case diffing \(lhs.value) with \(rhs.value) is not implemented.")
+            return false
+        }
+    }
+    
+    func isSimilar(to other: AnyRenderReference) -> Bool {
+        return self.value.identifier == other.value.identifier
+    }
+}

Sources/SwiftDocC/Model/Rendering/Diffing/AnyRenderSection.swift

@@ -0,0 +1,159 @@
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 2021-2023 Apple Inc. and the Swift project authors
+ Licensed under Apache License v2.0 with Runtime Library Exception
+
+ See https://swift.org/LICENSE.txt for license information
+ See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/
+
+/// A RenderSection value that can be diffed.
+///
+/// An `AnyRenderSection` value forwards difference operations to the underlying base type, each of which determine the difference differently.
+struct AnyRenderSection: Equatable, Encodable, RenderJSONDiffable {
+    var value: RenderSection
+    
+    init(_ value: RenderSection) {
+        self.value = value
+    }
+    
+    func encode(to encoder: Encoder) throws {
+        try value.encode(to: encoder)
+    }
+    
+    /// Forwards the difference methods on to the correct concrete type.
+    func difference(from other: AnyRenderSection, at path: CodablePath) -> JSONPatchDifferences {
+        switch (self.value.kind, other.value.kind) {
+            
+        // MARK: Symbol Sections
+            
+        case (.attributes, .attributes):
+            return (value as! AttributesRenderSection).difference(from: (other.value as! AttributesRenderSection), at: path)
+        case (.discussion, .discussion), (.content, .content):
+            return (value as! ContentRenderSection).difference(from: (other.value as! ContentRenderSection), at: path)
+        case (.declarations, .declarations):
+            return (value as! DeclarationsRenderSection).difference(from: (other.value as! DeclarationsRenderSection), at: path)
+        case (.parameters, .parameters):
+            return (value as! ParametersRenderSection).difference(from: (other.value as! ParametersRenderSection), at: path)
+        case (.plistDetails, .plistDetails):
+            return (value as! PlistDetailsRenderSection).difference(from: (other.value as! PlistDetailsRenderSection), at: path)
+        case (.possibleValues, .possibleValues):
+            return (value as! PossibleValuesRenderSection).difference(from: (other.value as! PossibleValuesRenderSection), at: path)
+        case (.relationships, .relationships):
+            return (value as! RelationshipsRenderSection).difference(from: (other.value as! RelationshipsRenderSection), at: path)
+        case (.restBody, .restBody):
+            return (value as! RESTBodyRenderSection).difference(from: (other.value as! RESTBodyRenderSection), at: path)
+        case (.restEndpoint, .restEndpoint):
+            return (value as! RESTEndpointRenderSection).difference(from: (other.value as! RESTEndpointRenderSection), at: path)
+        case (.restParameters, .restParameters):
+            return (value as! RESTParametersRenderSection).difference(from: (other.value as! RESTParametersRenderSection), at: path)
+        case (.restResponses, .restResponses):
+            return (value as! RESTResponseRenderSection).difference(from: (other.value as! RESTResponseRenderSection), at: path)
+        case (.sampleDownload, .sampleDownload):
+            return (value as! SampleDownloadSection).difference(from: (other.value as! SampleDownloadSection), at: path)
+        case (.taskGroup, .taskGroup):
+            return (value as! TaskGroupRenderSection).difference(from: (other.value as! TaskGroupRenderSection), at: path)
+            
+        // MARK: Tutorial Sections
+            
+        case (.intro, .intro), (.hero, .hero):
+            return (value as! IntroRenderSection).difference(from: (other.value as! IntroRenderSection), at: path)
+        case (.assessments, .assessments):
+            return (value as! TutorialAssessmentsRenderSection).difference(from: (other.value as! TutorialAssessmentsRenderSection), at: path)
+        case (.tasks, .tasks):
+            return (value as! TutorialSectionsRenderSection).difference(from: (other.value as! TutorialSectionsRenderSection), at: path)
+        
+        // MARK: Tutorial Article Sections
+            
+        case (.articleBody, .articleBody):
+            return (value as! TutorialArticleSection).difference(from: (other.value as! TutorialArticleSection), at: path)
+            
+        // MARK: Tutorials Overview Sections
+            
+        case (.callToAction, .callToAction):
+            return (value as! CallToActionSection).difference(from: (other.value as! CallToActionSection), at: path)
+        case (.contentAndMediaGroup, .contentAndMediaGroup):
+            return (value as! ContentAndMediaGroupSection).difference(from: (other.value as! ContentAndMediaGroupSection), at: path)
+        case (.contentAndMedia, .contentAndMedia):
+            return (value as! ContentAndMediaSection).difference(from: (other.value as! ContentAndMediaSection), at: path)
+        case (.resources, .resources):
+            return (value as! ResourcesRenderSection).difference(from: (other.value as! ResourcesRenderSection), at: path)
+        case (.volume, .volume):
+            return (value as! VolumeRenderSection).difference(from: (other.value as! VolumeRenderSection), at: path)
+            
+        default:
+            assertionFailure("Case diffing \(value) with \(other.value) is not implemented.")
+            return []
+        }
+    }
+
+    static func == (lhs: AnyRenderSection, rhs: AnyRenderSection) -> Bool {
+        switch (lhs.value.kind, rhs.value.kind) {
+            
+        // MARK: Symbol Sections
+            
+        case (.attributes, .attributes):
+            return (lhs.value as! AttributesRenderSection) == (rhs.value as! AttributesRenderSection)
+        case (.discussion, .discussion), (.content, .content):
+            return (lhs.value as! ContentRenderSection) == (rhs.value as! ContentRenderSection)
+        case (.declarations, .declarations):
+            return (lhs.value as! DeclarationsRenderSection) == (rhs.value as! DeclarationsRenderSection)
+        case (.parameters, .parameters):
+            return (lhs.value as! ParametersRenderSection) == (rhs.value as! ParametersRenderSection)
+        case (.plistDetails, .plistDetails):
+            return (lhs.value as! PlistDetailsRenderSection) == (rhs.value as! PlistDetailsRenderSection)
+        case (.possibleValues, .possibleValues):
+            return (lhs.value as! PossibleValuesRenderSection) == (rhs.value as! PossibleValuesRenderSection)
+        case (.relationships, .relationships):
+            return (lhs.value as! RelationshipsRenderSection) == (rhs.value as! RelationshipsRenderSection)
+        case (.restBody, .restBody):
+            return (lhs.value as! RESTBodyRenderSection) == (rhs.value as! RESTBodyRenderSection)
+        case (.restEndpoint, .restEndpoint):
+            return (lhs.value as! RESTEndpointRenderSection) == (rhs.value as! RESTEndpointRenderSection)
+        case (.restParameters, .restParameters):
+            return (lhs.value as! RESTParametersRenderSection) == (rhs.value as! RESTParametersRenderSection)
+        case (.restResponses, .restResponses):
+            return (lhs.value as! RESTResponseRenderSection) == (rhs.value as! RESTResponseRenderSection)
+        case (.sampleDownload, .sampleDownload):
+            return (lhs.value as! SampleDownloadSection) == (rhs.value as! SampleDownloadSection)
+        case (.taskGroup, .taskGroup):
+            return (lhs.value as! TaskGroupRenderSection) == (rhs.value as! TaskGroupRenderSection)
+            
+        // MARK: Tutorial Sections
+            
+        case (.intro, .intro), (.hero, .hero):
+            return (lhs.value as! IntroRenderSection) == (rhs.value as! IntroRenderSection)
+        case (.assessments, .assessments):
+            return (lhs.value as! TutorialAssessmentsRenderSection) == (rhs.value as! TutorialAssessmentsRenderSection)
+        case (.tasks, .tasks):
+            return (lhs.value as! TutorialSectionsRenderSection) == (rhs.value as! TutorialSectionsRenderSection)
+            
+        // MARK: Tutorial Article Sections
+            
+        case (.articleBody, .articleBody):
+            return (lhs.value as! TutorialArticleSection) == (rhs.value as! TutorialArticleSection)
+            
+        // MARK: Tutorials Overview Sections
+            
+        case (.callToAction, .callToAction):
+            return (lhs.value as! CallToActionSection) == (rhs.value as! CallToActionSection)
+        case (.contentAndMediaGroup, .contentAndMediaGroup):
+            return (lhs.value as! ContentAndMediaGroupSection) == (rhs.value as! ContentAndMediaGroupSection)
+        case (.contentAndMedia, .contentAndMedia):
+            return (lhs.value as! ContentAndMediaSection) == (rhs.value as! ContentAndMediaSection)
+        case (.resources, .resources):
+            return (lhs.value as! ResourcesRenderSection) == (rhs.value as! ResourcesRenderSection)
+        case (.volume, .volume):
+            return (lhs.value as! VolumeRenderSection) == (rhs.value as! VolumeRenderSection)
+        
+        default:
+            assertionFailure("Case diffing \(lhs.value) with \(rhs.value) is not implemented.")
+            return false
+        }
+    }
+    
+    func isSimilar(to other: AnyRenderSection) -> Bool {
+        return self.value.kind == other.value.kind
+    }
+}