Add Slice to replace Snippet Chunks (#50)

SE-0356 latest changes include parsing "slices" out of snippets.
These are not quite the same as the current "chunks", which were
a speculation that eventually formed into "slices". Deprecate chunks
and add the slice data model.

Move snippet presentation code to a line-based format: slices are represented
simply as a name and index range to pull their code lines.

Add the `isVirtual` property to modules, for modules that are created
implicitly to hold relationships. When snippet symbol graphs are created,
a fake module is created to hold the snippets, since snippets do not come
from any one module. This property simplifies what is basically just a
heuristic in DocC to a simple factual check.

Added round-trip decoding tests for `SymbolGraph.Module`.

rdar://95220716

Author: bitjammer

Sources/SymbolKit/SymbolGraph/Module.swift

@@ -12,7 +12,7 @@ import Foundation
 
 extension SymbolGraph {
     /// A ``Module-swift.struct``  describes the module from which the symbols were extracted..
-    public struct Module: Codable {
+    public struct Module: Codable, Equatable {
         /// The name of the module.
         public var name: String
 
@@ -25,11 +25,25 @@ extension SymbolGraph {
         /// The [semantic version](https://semver.org) of the module, if availble.
         public var version: SemanticVersion?
 
-        public init(name: String, platform: Platform, version: SemanticVersion? = nil, bystanders: [String]? = nil) {
+        /// `true` if the module represents a virtual module, not created from source,
+        /// but one created implicitly to hold relationships.
+        public var isVirtual: Bool = false
+
+        public init(name: String, platform: Platform, version: SemanticVersion? = nil, bystanders: [String]? = nil, isVirtual: Bool = false) {
             self.name = name
             self.platform = platform
             self.version = version
             self.bystanders = bystanders
+            self.isVirtual = isVirtual
+        }
+
+        public init(from decoder: Decoder) throws {
+            let container = try decoder.container(keyedBy: CodingKeys.self)
+            self.name = try container.decode(String.self, forKey: .name)
+            self.bystanders = try container.decodeIfPresent([String].self, forKey: .bystanders)
+            self.platform = try container.decode(Platform.self, forKey: .platform)
+            self.version = try container.decodeIfPresent(SemanticVersion.self, forKey: .version)
+            self.isVirtual = try container.decodeIfPresent(Bool.self, forKey: .isVirtual) ?? false
         }
     }
 }

Sources/SymbolKit/SymbolGraph/OperatingSystem.swift

@@ -12,7 +12,7 @@ extension SymbolGraph {
     /**
      The operating system intended for a ``Module-swift.struct``'s deployment.
      */
-    public struct OperatingSystem: Codable {
+    public struct OperatingSystem: Codable, Equatable {
         /**
          The name of the operating system, such as `macOS` or `Linux`.
          */

Sources/SymbolKit/SymbolGraph/Platform.swift

@@ -10,7 +10,7 @@
 
 extension SymbolGraph {
     /// A ``Platform`` describes the deployment environment for a ``Module-swift.struct``.
-    public struct Platform: Codable {
+    public struct Platform: Codable, Equatable {
         /**
          The name of the architecture that this module targets, such as `x86_64` or `arm64`. If the module doesn't have a specific architecture, this may be undefined.
          */

Sources/SymbolKit/SymbolGraph/Symbol/Snippet.swift

@@ -10,38 +10,82 @@
 
 extension SymbolGraph.Symbol {
     public struct Snippet: Mixin, Codable {
-        public struct Chunk: Codable {
-            public var name: String?
-            public var language: String?
-            public var code: String
-            public init(name: String?, language: String?, code: String) {
-                self.name = name
-                self.language = language
-                self.code = code
-            }
+        enum CodingKeys: String, CodingKey {
+            // TODO: Remove after obsoleting Chunks.
+            case chunks
+            case language
+            case slices
+            case lines
         }
 
         public static let mixinKey = "snippet"
-
-        public var chunks: [Chunk]
-
-        enum CodingKeys: String, CodingKey {
-            case chunks
+        
+        /// The language of the snippet if known.
+        public var language: String?
+        
+        /// The visible lines of code of the snippet to display.
+        public var lines: [String]
+        
+        /// Named spans of lines in the snippet.
+        public var slices: [String: Range<Int>]
+        
+        // TODO: Remove after obsoleting Chunks.
+        private var _chunks = [Chunk]()
+        
+        public init(language: String?, lines: [String], slices: [String: Range<Int>]) {
+            self.language = language
+            self.lines = lines
+            self.slices = slices
         }
 
         public init(from decoder: Decoder) throws {
             let container = try decoder.container(keyedBy: CodingKeys.self)
-            let chunks = try container.decode([Chunk].self, forKey: .chunks)
-            self.init(chunks: chunks)
+            let language = try container.decodeIfPresent(String.self, forKey: .language)
+            let lines = try container.decode([String].self, forKey: .lines)
+            let slices = try container.decodeIfPresent([String: Range<Int>].self, forKey: .slices) ?? [:]
+            self.init(language: language, lines: lines, slices: slices)
+            
+            // TODO: Remove after obsoleting Chunks.
+            self._chunks = try container.decodeIfPresent([Chunk].self, forKey: .chunks) ?? []
         }
 
         public func encode(to encoder: Encoder) throws {
             var container = encoder.container(keyedBy: CodingKeys.self)
-            try container.encode(chunks, forKey: .chunks)
+            try container.encodeIfPresent(language, forKey: .language)
+            try container.encode(lines, forKey: .lines)
+            if !slices.isEmpty {
+                try container.encode(slices, forKey: .slices)
+            }
+            if !_chunks.isEmpty {
+                try container.encode(_chunks, forKey: .chunks)
+            }
         }
+    }
+}
 
-        public init(chunks: [Chunk]) {
-            self.chunks = chunks
+extension SymbolGraph.Symbol.Snippet {
+    public struct Chunk: Codable {
+        public var name: String?
+        public var language: String?
+        public var code: String
+        @available(*, deprecated, message: "Chunks are no longer supported. Use `Slice` instead.")
+        public init(name: String?, language: String?, code: String) {
+            self.name = name
+            self.language = language
+            self.code = code
         }
     }
+    
+    @available(*, deprecated, message: "Chunks are no longer supported. Use `slices` instead.")
+    public var chunks: [Chunk] {
+        return _chunks
+    }
+    
+    @available(*, deprecated, renamed: "init(slices:)")
+    public init(chunks: [Chunk]) {
+        self._chunks = chunks
+        self.language = chunks.first?.language
+        self.slices = [:]
+        self.lines = []
+    }
 }

Sources/SymbolKit/SymbolGraph/Symbol/Symbol.swift

@@ -54,6 +54,9 @@ extension SymbolGraph {
         /// The in-source documentation comment attached to a symbol.
         public var docComment: LineList?
 
+        /// If true, the symbol was created implicitly and not from source.
+        public var isVirtual: Bool
+
         /// If the symbol has a documentation comment, whether the documentation comment is from
         /// the same module as the symbol or not.
         ///
@@ -102,13 +105,14 @@ extension SymbolGraph {
         /// Information about a symbol that is not necessarily common to all symbols.
         public var mixins: [String: Mixin] = [:]
 
-        public init(identifier: Identifier, names: Names, pathComponents: [String], docComment: LineList?, accessLevel: AccessControl, kind: Kind, mixins: [String: Mixin]) {
+        public init(identifier: Identifier, names: Names, pathComponents: [String], docComment: LineList?, accessLevel: AccessControl, kind: Kind, mixins: [String: Mixin], isVirtual: Bool = false) {
             self.identifier = identifier
             self.names = names
             self.pathComponents = pathComponents
             self.docComment = docComment
             self.accessLevel = accessLevel
             self.kind = kind
+            self.isVirtual = isVirtual
             self.mixins = mixins
         }
 
@@ -121,6 +125,7 @@ extension SymbolGraph {
             case names
             case docComment
             case accessLevel
+            case isVirtual
 
             // Mixins
             case availability
@@ -157,6 +162,7 @@ extension SymbolGraph {
             names = try container.decode(Names.self, forKey: .names)
             docComment = try container.decodeIfPresent(LineList.self, forKey: .docComment)
             accessLevel = try container.decode(AccessControl.self, forKey: .accessLevel)
+            isVirtual = try container.decodeIfPresent(Bool.self, forKey: .isVirtual) ?? false
             let leftoverMetadataKeys = Set(container.allKeys).intersection(CodingKeys.mixinKeys)
             for key in leftoverMetadataKeys {
                 if let decoded = try decodeMetadataItemForKey(key, from: container) {
@@ -178,6 +184,9 @@ extension SymbolGraph {
             try container.encode(names, forKey: .names)
             try container.encodeIfPresent(docComment, forKey: .docComment)
             try container.encode(accessLevel, forKey: .accessLevel)
+            if isVirtual {
+                try container.encode(isVirtual, forKey: .isVirtual)
+            }
 
             // Mixins
 

Sources/SymbolKit/UnifiedSymbolGraph/UnifiedSymbol.swift

@@ -44,6 +44,9 @@ extension UnifiedSymbolGraph {
         /// The access level of the symbol.
         public var accessLevel: [Selector: SymbolGraph.Symbol.AccessControl]
 
+        /// If true, the symbol was created implicitly and not from source.
+        public var isVirtual: [Selector: Bool]
+
         /// Information about a symbol that is not necessarily common to all symbols.
         public var mixins: [Selector: [String: Mixin]]
 
@@ -67,6 +70,7 @@ extension UnifiedSymbolGraph {
                 self.docComment[selector] = docComment
             }
             self.accessLevel = [selector: sym.accessLevel]
+            self.isVirtual = [selector: sym.isVirtual]
             self.mixins = [selector: sym.mixins]
         }
 
@@ -94,6 +98,7 @@ extension UnifiedSymbolGraph {
             self.names[selector] = symbol.names
             self.docComment[selector] = symbol.docComment
             self.accessLevel[selector] = symbol.accessLevel
+            self.isVirtual[selector] = symbol.isVirtual
             self.mixins[selector] = symbol.mixins
         }
     }

Tests/SymbolKitTests/SymbolGraph/ModuleTests.swift

@@ -0,0 +1,81 @@
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 2022 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
+*/
+
+import XCTest
+import SymbolKit
+
+extension SymbolGraph.Module {
+    func roundTripDecode() throws -> Self {
+        let encoder = JSONEncoder()
+        let encoded = try encoder.encode(self)
+        let decoder = JSONDecoder()
+        return try decoder.decode(SymbolGraph.Module.self, from: encoded)
+    }
+}
+
+class ModuleTests: XCTestCase {
+    static let os = SymbolGraph.OperatingSystem(name: "macOS", minimumVersion: .init(major: 10, minor: 9, patch: 0))
+    static let platform = SymbolGraph.Platform(architecture: "arm64", vendor: "Apple", operatingSystem: os)
+
+    func testFullRoundTripCoding() throws {
+        let module = SymbolGraph.Module(name: "Test", platform: ModuleTests.platform, bystanders: ["A"], isVirtual: true)
+        let decodedModule = try module.roundTripDecode()
+        XCTAssertEqual(module, decodedModule)
+    }
+    
+    func testOptionalBystanders() throws {
+        do {
+            // bystanders = nil
+            let module = SymbolGraph.Module(name: "Test", platform: ModuleTests.platform)
+            let decodedModule = try module.roundTripDecode()
+            XCTAssertNil(decodedModule.bystanders)
+        }
+        
+        do {
+            // bystanders = ["A"]
+            let module = SymbolGraph.Module(name: "Test", platform: ModuleTests.platform, bystanders: ["A"])
+            let decodedModule = try module.roundTripDecode()
+            XCTAssertEqual(["A"], decodedModule.bystanders)
+        }
+    }
+    
+    func testOptionalIsVirtual() throws {
+        do {
+            // isVirtual = false
+            let module = SymbolGraph.Module(name: "Test", platform: ModuleTests.platform)
+            let decodedModule = try module.roundTripDecode()
+            XCTAssertFalse(decodedModule.isVirtual)
+        }
+        
+        do {
+            // isVirtual = true
+            let module = SymbolGraph.Module(name: "Test", platform: ModuleTests.platform, isVirtual: true)
+            let decodedModule = try module.roundTripDecode()
+            XCTAssertTrue(decodedModule.isVirtual)
+        }
+    }
+    
+    func testOptionalVersion() throws {
+        do {
+            // version = nil
+            let module = SymbolGraph.Module(name: "Test", platform: ModuleTests.platform)
+            let decodedModule = try module.roundTripDecode()
+            XCTAssertNil(decodedModule.version)
+        }
+        
+        do {
+            // version = 1.0.0
+            let version = SymbolGraph.SemanticVersion(major: 1, minor: 0, patch: 0)
+            let module = SymbolGraph.Module(name: "Test", platform: ModuleTests.platform, version: version)
+            let decodedModule = try module.roundTripDecode()
+            XCTAssertEqual(version, decodedModule.version)
+        }
+    }
+}