Add mermaid charts support to swift package describe (#7289)

This adds support for new `--type mermaid` option on `swift package describe`.

This format is supported by the GitHub Markdown renderer and some Markdown preview extensions in IDEs.

I'm using different shapes to denote difference between products and targets. `| Foo |` is a target, `|| Bar ||` is a product, and hexagonal shapes declared with `{{ Baz }}` are products from package dependencies. I initially tried to include a legend subgraph, but that makes layout quite ugly even for simple packages, so I decided to exclude that by default. The codepath for rendering the legend is still there, so we can reenable it at any point or make conditional on some new CLI flag if needed.

Author: MaxDesiatov

Package.swift

@@ -387,6 +387,7 @@ let package = Package(
             name: "Commands",
             dependencies: [
                 .product(name: "ArgumentParser", package: "swift-argument-parser"),
+                .product(name: "OrderedCollections", package: "swift-collections"),
                 "Basics",
                 "Build",
                 "CoreCommands",

Sources/Commands/CMakeLists.txt

@@ -41,12 +41,15 @@ add_library(Commands
   Utilities/DependenciesSerializer.swift
   Utilities/DescribedPackage.swift
   Utilities/DOTManifestSerializer.swift
+  Utilities/MermaidPackageSerializer.swift
   Utilities/MultiRootSupport.swift
+  Utilities/PlainTextEncoder.swift
   Utilities/PluginDelegate.swift
   Utilities/SymbolGraphExtract.swift
   Utilities/TestingSupport.swift
   Utilities/XCTEvents.swift)
 target_link_libraries(Commands PUBLIC
+  SwiftCollections::OrderedCollections
   ArgumentParser
   Basics
   Build

Sources/Commands/PackageTools/Describe.swift

@@ -26,7 +26,7 @@ extension SwiftPackageTool {
         @OptionGroup(visibility: .hidden)
         var globalOptions: GlobalOptions
 
-        @Option(help: "json | text")
+        @Option(help: "json | text | mermaid")
         var type: DescribeMode = .text
 
         func run(_ swiftTool: SwiftTool) async throws {
@@ -57,6 +57,8 @@ extension SwiftPackageTool {
                 var encoder = PlainTextEncoder()
                 encoder.formattingOptions = [.prettyPrinted]
                 data = try encoder.encode(desc)
+            case .mermaid:
+                data = Data(MermaidPackageSerializer(package: package).renderedMarkdown.utf8)
             }
             print(String(decoding: data, as: UTF8.self))
         }
@@ -66,6 +68,8 @@ extension SwiftPackageTool {
             case json
             /// Human readable format (not guaranteed to be parsable).
             case text
+            /// Mermaid flow charts format
+            case mermaid
         }
     }
 }

Sources/Commands/Utilities/DOTManifestSerializer.swift

@@ -15,13 +15,13 @@ import LLBuildManifest
 import protocol TSCBasic.OutputByteStream
 
 /// Serializes an LLBuildManifest graph to a .dot file
-public struct DOTManifestSerializer {
+struct DOTManifestSerializer {
     var kindCounter = [String: Int]()
     var hasEmittedStyling = Set<String>()
     let manifest: LLBuildManifest
 
     /// Creates a serializer that will serialize the given manifest.
-    public init(manifest: LLBuildManifest) {
+    init(manifest: LLBuildManifest) {
         self.manifest = manifest
     }
 
@@ -38,11 +38,11 @@ public struct DOTManifestSerializer {
 
     /// Quote the name and escape the quotes and backslashes
     func quoteName(_ name: String) -> String {
-        return "\"" + name.replacingOccurrences(of: "\"", with: "\\\"")
-                          .replacingOccurrences(of: "\\", with: "\\\\") + "\""
+        "\"" + name.replacingOccurrences(of: "\"", with: "\\\"")
+            .replacingOccurrences(of: "\\", with: "\\\\") + "\""
     }
 
-    public mutating func writeDOT(to stream: OutputByteStream) {
+    mutating func writeDOT(to stream: OutputByteStream) {
         stream.write("digraph Jobs {\n")
         for (name, command) in manifest.commands {
             let jobName = quoteName(label(for: command))

Sources/Commands/Utilities/DescribedPackage.swift

@@ -114,7 +114,7 @@ struct DescribedPackage: Encodable {
             case registry
         }
 
-        public func encode(to encoder: Encoder) throws {
+        func encode(to encoder: Encoder) throws {
             var container = encoder.container(keyedBy: CodingKeys.self)
             switch self {
             case .fileSystem(let identity, let path):
@@ -258,232 +258,3 @@ struct DescribedPackage: Encodable {
         }
     }
 }
-
-
-public struct PlainTextEncoder {
-    
-    /// The formatting of the output plain-text data.
-    public struct FormattingOptions: OptionSet {
-        public let rawValue: UInt
-
-        public init(rawValue: UInt) {
-            self.rawValue = rawValue
-        }
-
-        /// Produce plain-text format with indented output.
-        public static let prettyPrinted = FormattingOptions(rawValue: 1 << 0)
-    }
-
-    /// The output format to produce. Defaults to `[]`.
-    var formattingOptions: FormattingOptions = []
-
-    /// Contextual user-provided information for use during encoding.
-    var userInfo: [CodingUserInfoKey: Any] = [:]
-
-    /// Encodes the given top-level value and returns its plain text representation.
-    ///
-    /// - parameter value: The value to encode.
-    /// - returns: A new `Data` value containing the encoded plan-text data.
-    /// - throws: An error if any value throws an error during encoding.
-    func encode<T: Encodable>(_ value: T) throws -> Data {
-        let outputStream = BufferedOutputByteStream()
-        let encoder = _PlainTextEncoder(outputStream: outputStream, formattingOptions: formattingOptions, userInfo: userInfo)
-        try value.encode(to: encoder)
-        return Data(outputStream.bytes.contents)
-    }
-    
-    /// Private helper function to format key names with an uppercase initial letter and space-separated components.
-    private static func displayName(for key: CodingKey) -> String {
-        var result = ""
-        for ch in key.stringValue {
-            if result.isEmpty {
-                result.append(ch.uppercased())
-            }
-            else if ch.isUppercase {
-                result.append(" ")
-                result.append(ch.lowercased())
-            }
-            else {
-                result.append(ch)
-            }
-        }
-        return result
-    }
-    
-    /// Private Encoder implementation for PlainTextEncoder.
-    private struct _PlainTextEncoder: Encoder {
-        /// Output stream.
-        var outputStream: OutputByteStream
-
-        /// Formatting options set on the top-level encoder.
-        let formattingOptions: PlainTextEncoder.FormattingOptions
-
-        /// Contextual user-provided information for use during encoding.
-        let userInfo: [CodingUserInfoKey: Any]
-
-        /// The path to the current point in encoding.
-        let codingPath: [CodingKey]
-
-        /// Initializes `self` with the given top-level encoder options.
-        init(outputStream: OutputByteStream, formattingOptions: PlainTextEncoder.FormattingOptions, userInfo: [CodingUserInfoKey: Any], codingPath: [CodingKey] = []) {
-            self.outputStream = outputStream
-            self.formattingOptions = formattingOptions
-            self.userInfo = userInfo
-            self.codingPath = codingPath
-        }
-
-        func container<Key: CodingKey>(keyedBy type: Key.Type) -> KeyedEncodingContainer<Key> {
-            return KeyedEncodingContainer(PlainTextKeyedEncodingContainer<Key>(outputStream: outputStream, formattingOptions: formattingOptions, userInfo: userInfo, codingPath: codingPath))
-        }
-        
-        func unkeyedContainer() -> UnkeyedEncodingContainer {
-            return PlainTextUnkeyedEncodingContainer(outputStream: outputStream, formattingOptions: formattingOptions, userInfo: userInfo, codingPath: codingPath)
-        }
-        
-        func singleValueContainer() -> SingleValueEncodingContainer {
-            return TextSingleValueEncodingContainer(outputStream: outputStream, formattingOptions: formattingOptions, userInfo: userInfo, codingPath: codingPath)
-        }
-
-        /// Private KeyedEncodingContainer implementation for PlainTextEncoder.
-        private struct PlainTextKeyedEncodingContainer<Key: CodingKey>: KeyedEncodingContainerProtocol {
-            let outputStream: OutputByteStream
-            let formattingOptions: PlainTextEncoder.FormattingOptions
-            let userInfo: [CodingUserInfoKey: Any]
-            let codingPath: [CodingKey]
-            
-            private mutating func emit(_ key: CodingKey, _ value: String?) {
-                outputStream.send("\(String(repeating: "    ", count: codingPath.count))\(displayName(for: key)):")
-                if let value { outputStream.send(" \(value)") }
-                outputStream.send("\n")
-            }
-            mutating func encodeNil(forKey key: Key) throws { emit(key, "nil") }
-            mutating func encode(_ value: Bool, forKey key: Key) throws { emit(key, "\(value)") }
-            mutating func encode(_ value: String, forKey key: Key) throws { emit(key, "\(value)") }
-            mutating func encode(_ value: Double, forKey key: Key) throws { emit(key, "\(value)") }
-            mutating func encode(_ value: Float, forKey key: Key) throws { emit(key, "\(value)") }
-            mutating func encode(_ value: Int, forKey key: Key) throws { emit(key, "\(value)") }
-            mutating func encode(_ value: Int8, forKey key: Key) throws { emit(key, "\(value)") }
-            mutating func encode(_ value: Int16, forKey key: Key) throws { emit(key, "\(value)") }
-            mutating func encode(_ value: Int32, forKey key: Key) throws { emit(key, "\(value)") }
-            mutating func encode(_ value: Int64, forKey key: Key) throws { emit(key, "\(value)") }
-            mutating func encode(_ value: UInt, forKey key: Key) throws { emit(key, "\(value)") }
-            mutating func encode(_ value: UInt8, forKey key: Key) throws { emit(key, "\(value)") }
-            mutating func encode(_ value: UInt16, forKey key: Key) throws { emit(key, "\(value)") }
-            mutating func encode(_ value: UInt32, forKey key: Key) throws { emit(key, "\(value)") }
-            mutating func encode(_ value: UInt64, forKey key: Key) throws { emit(key, "\(value)") }
-            mutating func encode<T: Encodable>(_ value: T, forKey key: Key) throws {
-                emit(key, nil)
-                let textEncoder = _PlainTextEncoder(outputStream: outputStream, formattingOptions: formattingOptions, userInfo: userInfo, codingPath: codingPath + [key])
-                try value.encode(to: textEncoder)
-            }
-            
-            mutating func nestedContainer<NestedKey: CodingKey>(keyedBy keyType: NestedKey.Type, forKey key: Key) -> KeyedEncodingContainer<NestedKey> {
-                emit(key, nil)
-                return KeyedEncodingContainer(PlainTextKeyedEncodingContainer<NestedKey>(outputStream: outputStream, formattingOptions: formattingOptions, userInfo: userInfo, codingPath: codingPath + [key]))
-            }
-            
-            mutating func nestedUnkeyedContainer(forKey key: Key) -> UnkeyedEncodingContainer {
-                emit(key, nil)
-                return PlainTextUnkeyedEncodingContainer(outputStream: outputStream, formattingOptions: formattingOptions, userInfo: userInfo, codingPath: codingPath + [key])
-            }
-            
-            mutating func superEncoder() -> Encoder {
-                return superEncoder(forKey: Key(stringValue: "super")!)
-            }
-            
-            mutating func superEncoder(forKey key: Key) -> Encoder {
-                return _PlainTextEncoder(outputStream: outputStream, formattingOptions: formattingOptions, userInfo: userInfo, codingPath: codingPath + [key])
-            }
-        }
-        
-        /// Private UnkeyedEncodingContainer implementation for PlainTextEncoder.
-        private struct PlainTextUnkeyedEncodingContainer: UnkeyedEncodingContainer {
-            let outputStream: OutputByteStream
-            let formattingOptions: PlainTextEncoder.FormattingOptions
-            let userInfo: [CodingUserInfoKey: Any]
-            let codingPath: [CodingKey]
-            private(set) var count: Int = 0
-            
-            private mutating func emit(_ value: String) {
-                outputStream.send("\(String(repeating: "    ", count: codingPath.count))\(value)\n")
-                count += 1
-            }
-            mutating func encodeNil() throws { emit("nil") }
-            mutating func encode(_ value: Bool) throws { emit("\(value)") }
-            mutating func encode(_ value: String) throws { emit("\(value)") }
-            mutating func encode(_ value: Double) throws { emit("\(value)") }
-            mutating func encode(_ value: Float) throws { emit("\(value)") }
-            mutating func encode(_ value: Int) throws { emit("\(value)") }
-            mutating func encode(_ value: Int8) throws { emit("\(value)") }
-            mutating func encode(_ value: Int16) throws { emit("\(value)") }
-            mutating func encode(_ value: Int32) throws { emit("\(value)") }
-            mutating func encode(_ value: Int64) throws { emit("\(value)") }
-            mutating func encode(_ value: UInt) throws { emit("\(value)") }
-            mutating func encode(_ value: UInt8) throws { emit("\(value)") }
-            mutating func encode(_ value: UInt16) throws { emit("\(value)") }
-            mutating func encode(_ value: UInt32) throws { emit("\(value)") }
-            mutating func encode(_ value: UInt64) throws { emit("\(value)") }
-            mutating func encode<T: Encodable>(_ value: T) throws {
-                let textEncoder = _PlainTextEncoder(
-                    outputStream: outputStream,
-                    formattingOptions: formattingOptions,
-                    userInfo: userInfo,
-                    codingPath: codingPath
-                )
-                try value.encode(to: textEncoder)
-                count += 1
-                // FIXME: This is a bit arbitrary and should be controllable.  We may also want an option to only emit
-                // newlines between entries, not after each one.
-                if codingPath.count < 2 { outputStream.send("\n") }
-            }
-            
-            mutating func nestedContainer<NestedKey: CodingKey>(keyedBy keyType: NestedKey.Type) -> KeyedEncodingContainer<NestedKey> {
-                KeyedEncodingContainer(PlainTextKeyedEncodingContainer<NestedKey>(
-                    outputStream: outputStream,
-                    formattingOptions: formattingOptions,
-                    userInfo: userInfo,
-                    codingPath: codingPath
-                ))
-            }
-            
-            mutating func nestedUnkeyedContainer() -> UnkeyedEncodingContainer {
-                return PlainTextUnkeyedEncodingContainer(outputStream: outputStream, formattingOptions: formattingOptions, userInfo: userInfo, codingPath: codingPath)
-            }
-            
-            mutating func superEncoder() -> Encoder {
-                return _PlainTextEncoder(outputStream: outputStream, formattingOptions: formattingOptions, userInfo: userInfo, codingPath: codingPath)
-            }
-        }
-        
-        /// Private SingleValueEncodingContainer implementation for PlainTextEncoder.
-        private struct TextSingleValueEncodingContainer: SingleValueEncodingContainer {
-            let outputStream: OutputByteStream
-            let formattingOptions: PlainTextEncoder.FormattingOptions
-            let userInfo: [CodingUserInfoKey: Any]
-            let codingPath: [CodingKey]
-            
-            private mutating func emit(_ value: String) {
-                outputStream.send("\(String(repeating: "    ", count: codingPath.count))\(value)\n")
-            }
-            mutating func encodeNil() throws { emit("nil") }
-            mutating func encode(_ value: Bool) throws { emit("\(value)") }
-            mutating func encode(_ value: String) throws { emit("\(value)") }
-            mutating func encode(_ value: Double) throws { emit("\(value)") }
-            mutating func encode(_ value: Float) throws { emit("\(value)") }
-            mutating func encode(_ value: Int) throws { emit("\(value)") }
-            mutating func encode(_ value: Int8) throws { emit("\(value)") }
-            mutating func encode(_ value: Int16) throws { emit("\(value)") }
-            mutating func encode(_ value: Int32) throws { emit("\(value)") }
-            mutating func encode(_ value: Int64) throws { emit("\(value)") }
-            mutating func encode(_ value: UInt) throws { emit("\(value)") }
-            mutating func encode(_ value: UInt8) throws { emit("\(value)") }
-            mutating func encode(_ value: UInt16) throws { emit("\(value)") }
-            mutating func encode(_ value: UInt32) throws { emit("\(value)") }
-            mutating func encode(_ value: UInt64) throws { emit("\(value)") }
-            mutating func encode<T: Encodable>(_ value: T) throws {
-                let textEncoder = _PlainTextEncoder(outputStream: outputStream, formattingOptions: formattingOptions, userInfo: userInfo, codingPath: codingPath)
-                try value.encode(to: textEncoder)
-            }
-        }
-    }
-}