Add experimental swift-api-diagram executable

Author: mattt

Package.swift

@@ -23,6 +23,10 @@ let package = Package(
             name: "swift-dcov",
             dependencies: ["SwiftSyntax", "SwiftSemantics", "SwiftMarkup", "SwiftDoc", "Commander"]
         ),
+        .target(
+            name: "swift-api-diagram",
+            dependencies: ["SwiftDoc", "SwiftSemantics", "Commander"]
+        ),
         .target(
             name: "swift-api-inventory",
             dependencies: ["SwiftDoc", "SwiftSemantics", "Commander"]

README.md

@@ -217,6 +217,33 @@ $ diff -u Alamofire-5.0.0-rc.1.txt Alamofire-5.0.0-rc.3.txt
 
 </details>
 
+### swift-api-diagram
+
+`swift-dcov` generates a graph of APIs in [DOT format][dot]
+that can be rendered by [GraphViz][graphviz] into a diagram.
+
+```terminal
+$ swift run swift-api-diagram Alamofire/Source > graph.dot
+$ head graph.dot
+digraph Anonymous {
+  "Session" [shape=box];
+  "NetworkReachabilityManager" [shape=box];
+  "URLEncodedFormEncoder" [shape=box,peripheries=2];
+  "ServerTrustManager" [shape=box];
+  "MultipartFormData" [shape=box];
+  
+  subgraph cluster_Request {
+    "DataRequest" [shape=box];
+    "Request" [shape=box];
+
+$ dot -T svg graph.dot > graph.svg
+```
+
+Here's an excerpt of the graph generated for Alamofire:
+
+![Excerpt of swift-doc-api Diagram for Alamofire](https://user-images.githubusercontent.com/7659/73189318-0db0e880-40d9-11ea-8895-341a75ce873c.png)
+
+
 ## Motivation
 
 From its earliest days,
@@ -389,3 +416,5 @@ Mattt ([@mattt](https://twitter.com/mattt))
 [nshipster]: https://nshipster.com
 [dependency hell]: https://github.com/apple/swift-package-manager/tree/master/Documentation#dependency-hell
 [pcre]: https://en.wikipedia.org/wiki/Perl_Compatible_Regular_Expressions
+[dot]: https://en.wikipedia.org/wiki/DOT_(graph_description_language)
+[graphviz]: https://www.graphviz.org

Sources/swift-api-diagram/Extensions/FileHandle+TextOutputStream.swift

@@ -0,0 +1,8 @@
+import Foundation
+
+extension FileHandle: TextOutputStream {
+    public func write(_ string: String) {
+        guard let data = string.data(using: .utf8) else { return }
+        write(data)
+    }
+}

Sources/swift-api-diagram/Extensions/SwiftDoc+Extensions.swift

@@ -0,0 +1,15 @@
+import SwiftDoc
+import SwiftSemantics
+
+extension Modifiable {
+    var nonAccessModifiers: [Modifier] {
+        return modifiers.filter { modifier in
+            switch modifier.name {
+            case "private", "fileprivate", "internal", "public", "open":
+                return false
+            default:
+                return true
+            }
+        }
+    }
+}

Sources/swift-api-diagram/Extensions/SwiftSemantics+Extensions.swift

@@ -0,0 +1,15 @@
+import SwiftSemantics
+
+protocol Generic {
+    var genericParameters: [GenericParameter] { get }
+    var genericRequirements: [GenericRequirement] { get }
+}
+
+extension Class: Generic {}
+extension Enumeration: Generic {}
+extension Function: Generic {}
+extension Initializer: Generic {}
+extension Structure: Generic {}
+extension Subscript: Generic {}
+extension Typealias: Generic {}
+

Sources/swift-api-diagram/GraphViz.swift

@@ -0,0 +1,100 @@
+import SwiftSemantics
+import SwiftDoc
+
+fileprivate extension String {
+    func indented(by spaces: Int = 2) -> String {
+        return String(repeating: " ", count: spaces) + self
+    }
+}
+
+// MARK: -
+
+enum GraphViz {
+    static func diagram(of module: Module) -> String {
+        var lines: [String] = []
+
+        var baseClasses: Set<String> = []
+        var inheritanceMappings: [String: String] = [:]
+
+        let symbols = module.symbols.filter { $0.declaration.isPublic }
+
+        let classes = symbols.filter { $0.declaration is Class }
+        for `class` in classes {
+            if let declaration = `class`.declaration as? Class,
+                let firstInheritedType = declaration.inheritance.first
+            {
+                if classes.contains(where: { $0.declaration.name.hasSuffix(firstInheritedType) }) {
+                    inheritanceMappings[`class`.declaration.qualifiedName] = firstInheritedType
+                }
+            } else {
+                baseClasses.insert(`class`.declaration.qualifiedName)
+            }
+        }
+
+        var classClusters: [String: Set<String>] = [:]
+        for baseClass in baseClasses {
+            var cluster: Set<String> = [baseClass]
+
+            var previousCount = -1
+            while cluster.count > previousCount {
+                previousCount = cluster.count
+                for (subclass, superclass) in inheritanceMappings {
+                    if cluster.contains(superclass) {
+                        cluster.insert(subclass)
+                    }
+                }
+            }
+
+            classClusters[baseClass] = cluster
+        }
+
+        for (baseClass, cluster) in classClusters {
+            var clusterLines: [String] = []
+
+            for className in cluster {
+                if let `class` = classes.first(where: { $0.declaration.qualifiedName == className }),
+                    let declaration = `class`.declaration as? Class,
+                    declaration.modifiers.contains(where: { $0.name == "final" }) == true
+                {
+                    clusterLines.append(#""\#(className)" [shape=box,peripheries=2];"#)
+                } else {
+                    clusterLines.append(#""\#(className)" [shape=box];"#)
+                }
+            }
+
+            if cluster.count > 1 {
+                for (subclassName, superclassName) in inheritanceMappings {
+                    if cluster.contains(superclassName) {
+                        clusterLines.append(#""\#(subclassName)" -> "\#(superclassName)";"#)
+                    }
+                }
+
+                clusterLines = (
+                    ["", "subgraph cluster_\(baseClass) {"] +
+                    clusterLines.map { $0.indented() } +
+                    ["}", ""]
+                )
+            }
+
+            lines.append(contentsOf: clusterLines)
+        }
+
+        lines.append("")
+
+        for symbol in (symbols.filter { $0.declaration is Type }) {
+            guard let type = symbol.declaration as? Type else { continue }
+            for item in type.inheritance {
+                guard !inheritanceMappings.values.contains(item) else { continue }
+                for inherited in item.split(separator: "&").map({ String($0).trimmingCharacters(in: .whitespacesAndNewlines) }) {
+                    lines.append(#""\#(type.qualifiedName)" -> "\#(inherited)";"#)
+                }
+            }
+        }
+
+        lines = ["digraph \(module.name) {"] +
+                    lines.map { $0.indented() } +
+                ["}"]
+
+        return lines.joined(separator: "\n")
+    }
+}

Sources/swift-api-diagram/main.swift

@@ -0,0 +1,37 @@
+import Commander
+import Foundation
+import SwiftDoc
+
+let arguments = Array(ProcessInfo.processInfo.arguments.dropFirst())
+
+let fileManager = FileManager.default
+
+var standardOutput = FileHandle.standardOutput
+var standardError = FileHandle.standardError
+
+command(
+    Argument<[String]>("inputs", description: "One or more paths to Swift files", validator: { (inputs) -> [String] in
+        inputs.filter { path in
+            var isDirectory: ObjCBool = false
+            return fileManager.fileExists(atPath: path, isDirectory: &isDirectory) || isDirectory.boolValue
+        }
+    }), { inputs in
+        do {
+            // TODO: Add special behavior for Package.swift manifests
+            var sourceFiles: [SourceFile] = []
+            for path in inputs {
+                let directory = URL(fileURLWithPath: path)
+                guard let directoryEnumerator = fileManager.enumerator(at: directory, includingPropertiesForKeys: nil) else { continue }
+                for case let url as URL in directoryEnumerator {
+                    guard url.pathExtension == "swift" else { continue }
+                    sourceFiles.append(try SourceFile(file: url, relativeTo: directory))
+                }
+            }
+
+            let module = Module(sourceFiles: sourceFiles)
+            print(GraphViz.diagram(of: module), to: &standardOutput)
+        } catch {
+            print("Error: \(error)", to: &standardError)
+            exit(EXIT_FAILURE)
+        }
+}).run()