Add UndirectedGraph and DirectedGraph data structures (#7460)

`DirectedGraph` can be used to represent the existing modules graph in the `PackageGraph` module hopefully with better performance due to reduced number of allocations. `UndirectedGraph` could represent a new linkage graph concept, which would help with breaking dependency cycles for certain packages with products that don't have a linkage cycle.

I started with an adjacency list in a directed graph implementation, but then proceeded to an undirected graph where adjacency matrix seemed obviously more performant when adding edges: just flipping two bits in the matrix instead of adding potential array (re-)allocations with the list.

I'm unsure though if either is a clear win in all cases, adjacency matrix may be fast at adding edges, but not the fastest for different kinds of graphs analysis and lookups. Keeping both implementations for future reference.

Author: MaxDesiatov

Sources/Basics/CMakeLists.txt

@@ -34,6 +34,9 @@ add_library(Basics
   FileSystem/TemporaryFile.swift
   FileSystem/TSCAdapters.swift
   FileSystem/VFSOverlay.swift
+  Graph/AdjacencyMatrix.swift
+  Graph/DirectedGraph.swift
+  Graph/UndirectedGraph.swift
   SourceControlURL.swift
   HTTPClient/HTTPClient.swift
   HTTPClient/HTTPClientConfiguration.swift

Sources/Basics/Graph/AdjacencyMatrix.swift

@@ -0,0 +1,61 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift open source project
+//
+// Copyright (c) 2024 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See http://swift.org/LICENSE.txt for license information
+// See http://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
+//
+//===----------------------------------------------------------------------===//
+
+/// A matrix storing bits of `true`/`false` state for a given combination of row and column indices. Used as
+/// a square matrix indicating edges in graphs, where rows and columns are indices in a storage of graph's nodes.
+///
+/// For example, in a graph that contains 3 nodes `matrix[row: 1, column: 2]` evaluating to `true` means an edge
+/// between nodes with indices `1` and `2` exists. `matrix[row: 1, column: 2]` evaluating to `false` means that no
+/// edge exists.
+///
+/// See https://en.wikipedia.org/wiki/Adjacency_matrix for more details.
+struct AdjacencyMatrix {
+    let columns: Int
+    let rows: Int
+    private var bytes: [UInt8]
+
+    /// Allocates a new bit matrix with a given size.
+    /// - Parameters:
+    ///   - rows: Number of rows in the matrix.
+    ///   - columns: Number of columns in the matrix.
+    init(rows: Int, columns: Int) {
+        self.columns = columns
+        self.rows = rows
+        
+        let (quotient, remainder) = (rows * columns).quotientAndRemainder(dividingBy: 8)
+        self.bytes = .init(repeating: 0, count: quotient + (remainder > 0 ? 1 : 0))
+    }
+
+    var bitCount: Int {
+        bytes.count * 8
+    }
+
+    private func calculateOffsets(row: Int, column: Int) -> (byteOffset: Int, bitOffsetInByte: Int) {
+        let totalBitOffset = row * columns + column
+        return (byteOffset: totalBitOffset / 8, bitOffsetInByte: totalBitOffset % 8)
+    }
+
+    subscript(row: Int, column: Int) -> Bool {
+        get {
+            let (byteOffset, bitOffsetInByte) = calculateOffsets(row: row, column: column)
+
+            let result = (self.bytes[byteOffset] >> bitOffsetInByte) & 1
+            return result == 1
+        }
+
+        set {
+            let (byteOffset, bitOffsetInByte) = calculateOffsets(row: row, column: column)
+
+            self.bytes[byteOffset] |= 1 << bitOffsetInByte
+        }
+    }
+}

Sources/Basics/Graph/DirectedGraph.swift

@@ -0,0 +1,54 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift open source project
+//
+// Copyright (c) 2024 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See http://swift.org/LICENSE.txt for license information
+// See http://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
+//
+//===----------------------------------------------------------------------===//
+
+import struct DequeModule.Deque
+
+/// Directed graph that stores edges in [adjacency lists](https://en.wikipedia.org/wiki/Adjacency_list).
+struct DirectedGraph<Node> {
+    init(nodes: [Node]) {
+        self.nodes = nodes
+        self.edges = .init(repeating: [], count: nodes.count)
+    }
+
+    private var nodes: [Node]
+    private var edges: [[Int]]
+
+    mutating func addEdge(source: Int, destination: Int) {
+        self.edges[source].append(destination)
+    }
+    
+    /// Checks whether a path via previously created edges between two given nodes exists.
+    /// - Parameters:
+    ///   - source: `Index` of a node to start traversing edges from.
+    ///   - destination: `Index` of a node to which a path could exist via edges from `source`.
+    /// - Returns: `true` if a path from `source` to `destination` exists, `false` otherwise.
+    func areNodesConnected(source: Int, destination: Int) -> Bool {
+        var todo = Deque<Int>([source])
+        var done = Set<Int>()
+
+        while !todo.isEmpty {
+            let nodeIndex = todo.removeFirst()
+
+            for reachableIndex in self.edges[nodeIndex] {
+                if reachableIndex == destination {
+                    return true
+                } else if !done.contains(reachableIndex) {
+                    todo.append(reachableIndex)
+                }
+            }
+
+            done.insert(nodeIndex)
+        }
+
+        return false
+    }
+}

Sources/Basics/Graph/UndirectedGraph.swift

@@ -0,0 +1,68 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift open source project
+//
+// Copyright (c) 2024 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See http://swift.org/LICENSE.txt for license information
+// See http://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
+//
+//===----------------------------------------------------------------------===//
+
+import struct DequeModule.Deque
+
+/// Undirected graph that stores edges in an [adjacency matrix](https://en.wikipedia.org/wiki/Adjacency_list).
+struct UndirectedGraph<Node> {
+    init(nodes: [Node]) {
+        self.nodes = nodes
+        self.edges = .init(rows: nodes.count, columns: nodes.count)
+    }
+
+    private var nodes: [Node]
+    private var edges: AdjacencyMatrix
+
+    mutating func addEdge(source: Int, destination: Int) {
+        // Adjacency matrix is symmetrical for undirected graphs.
+        self.edges[source, destination] = true
+        self.edges[destination, source] = true
+    }
+
+    /// Checks whether a connection via previously created edges between two given nodes exists.
+    /// - Parameters:
+    ///   - source: `Index` of a node to start traversing edges from.
+    ///   - destination: `Index` of a node to which a connection could exist via edges from `source`.
+    /// - Returns: `true` if a path from `source` to `destination` exists, `false` otherwise.
+    func areNodesConnected(source: Int, destination: Int) -> Bool {
+        var todo = Deque<Int>([source])
+        var done = Set<Int>()
+
+        while !todo.isEmpty {
+            let nodeIndex = todo.removeFirst()
+
+            for reachableIndex in self.edges.nodesAdjacentTo(nodeIndex) {
+                if reachableIndex == destination {
+                    return true
+                } else if !done.contains(reachableIndex) {
+                    todo.append(reachableIndex)
+                }
+            }
+
+            done.insert(nodeIndex)
+        }
+
+        return false
+    }
+}
+
+private extension AdjacencyMatrix {
+    func nodesAdjacentTo(_ nodeIndex: Int) -> [Int] {
+        var result = [Int]()
+
+        for i in 0..<self.rows where self[i, nodeIndex] {
+            result.append(i)
+        }
+
+        return result
+    }
+}

Tests/BasicsTests/Graph/AdjacencyMatrixTests.swift

@@ -0,0 +1,40 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift open source project
+//
+// Copyright (c) 2024 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See http://swift.org/LICENSE.txt for license information
+// See http://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
+//
+//===----------------------------------------------------------------------===//
+
+@testable import Basics
+import XCTest
+
+final class AdjacencyMatrixTests: XCTestCase {
+    func testEmpty() {
+        var matrix = AdjacencyMatrix(rows: 0, columns: 0)
+        XCTAssertEqual(matrix.bitCount, 0)
+
+        matrix = AdjacencyMatrix(rows: 0, columns: 42)
+        XCTAssertEqual(matrix.bitCount, 0)
+
+        matrix = AdjacencyMatrix(rows: 42, columns: 0)
+        XCTAssertEqual(matrix.bitCount, 0)
+    }
+
+    func testBits() {
+        for count in 1..<10 {
+            var matrix = AdjacencyMatrix(rows: count, columns: count)
+            for row in 0..<count {
+                for column in 0..<count {
+                    XCTAssertFalse(matrix[row, column])
+                    matrix[row, column] = true
+                    XCTAssertTrue(matrix[row, column])
+                }
+            }
+        }
+    }
+}

Tests/BasicsTests/Graph/DirectedGraphTests.swift

@@ -0,0 +1,31 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift open source project
+//
+// Copyright (c) 2024 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See http://swift.org/LICENSE.txt for license information
+// See http://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
+//
+//===----------------------------------------------------------------------===//
+
+@testable import Basics
+import XCTest
+
+final class DirectedGraphTests: XCTestCase {
+    func testNodesConnection() {
+        var graph = DirectedGraph(nodes: ["app1", "lib1", "lib2", "app2", "lib3"])
+        graph.addEdge(source: 0, destination: 1)
+        graph.addEdge(source: 1, destination: 2)
+        XCTAssertTrue(graph.areNodesConnected(source: 0, destination: 2))
+        XCTAssertFalse(graph.areNodesConnected(source: 2, destination: 0))
+
+        graph.addEdge(source: 0, destination: 4)
+        graph.addEdge(source: 3, destination: 4)
+        XCTAssertTrue(graph.areNodesConnected(source: 3, destination: 4))
+        XCTAssertTrue(graph.areNodesConnected(source: 0, destination: 4))
+        XCTAssertFalse(graph.areNodesConnected(source: 1, destination: 4))
+        XCTAssertTrue(graph.areNodesConnected(source: 0, destination: 4))
+    }
+}

Tests/BasicsTests/Graph/UndirectedGraphTests.swift

@@ -0,0 +1,38 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift open source project
+//
+// Copyright (c) 2024 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See http://swift.org/LICENSE.txt for license information
+// See http://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
+//
+//===----------------------------------------------------------------------===//
+
+@testable import Basics
+import XCTest
+
+final class UndirectedGraphTests: XCTestCase {
+    func testNodesConnection() {
+        var graph = UndirectedGraph(nodes: ["app1", "lib1", "lib2", "app2", "lib3", "app3"])
+        graph.addEdge(source: 0, destination: 1)
+        graph.addEdge(source: 1, destination: 2)
+        XCTAssertTrue(graph.areNodesConnected(source: 0, destination: 2))
+        XCTAssertTrue(graph.areNodesConnected(source: 2, destination: 0))
+
+        graph.addEdge(source: 0, destination: 4)
+        graph.addEdge(source: 3, destination: 4)
+        XCTAssertTrue(graph.areNodesConnected(source: 3, destination: 4))
+        XCTAssertTrue(graph.areNodesConnected(source: 4, destination: 3))
+        XCTAssertTrue(graph.areNodesConnected(source: 0, destination: 4))
+        XCTAssertTrue(graph.areNodesConnected(source: 4, destination: 0))
+        XCTAssertTrue(graph.areNodesConnected(source: 1, destination: 4))
+        XCTAssertTrue(graph.areNodesConnected(source: 4, destination: 1))
+
+        for i in 0...4 {
+            XCTAssertFalse(graph.areNodesConnected(source: i, destination: 5))
+            XCTAssertFalse(graph.areNodesConnected(source: 5, destination: i))
+        }
+    }
+}