[NFC-ish] Factor out CompatibilityLayer

A new CompatibilityLayer type computes information about deprecated vars and inits, presenting it in a new way: by creating additional `Child` objects with the deprecated information, plus sufficient info to map it back to the current name.

This causes minor non-functional changes to the bodies of compatibility builder inits, but otherwise has no real effect in this commit. However, this new setup with separate `Child` nodes for deprecated children and a global table of information about them prepares us for further changes.

Author: beccadax

CodeGeneration/Sources/SyntaxSupport/Child.swift

@@ -150,30 +150,43 @@ public class Child: NodeChoiceConvertible {
   /// For any other kind of child nodes, accessing this property crashes.
   public var syntaxChoicesType: TypeSyntax {
     precondition(kind.isNodeChoices, "Cannot get `syntaxChoicesType` for node that doesn’t have nodeChoices")
-    return "\(raw: name.withFirstCharacterUppercased)"
+    return "\(raw: newestName.withFirstCharacterUppercased)"
   }
 
   /// If this child only has tokens, the type that the generated `TokenSpecSet` should get.
   ///
   /// For any other kind of child nodes, accessing this property crashes.
   public var tokenSpecSetType: TypeSyntax {
     precondition(kind.isToken, "Cannot get `tokenSpecSetType` for node that isn’t a token")
-    return "\(raw: name.withFirstCharacterUppercased)Options"
-  }
-
-  /// The deprecated name of this child that's suitable to be used for variable or enum case names.
-  public var deprecatedVarName: TokenSyntax? {
-    guard let deprecatedName = deprecatedName else {
-      return nil
-    }
-    return .identifier(lowercaseFirstWord(name: deprecatedName))
+    return "\(raw: newestName.withFirstCharacterUppercased)Options"
   }
 
   /// Determines if this child has a deprecated name
   public var hasDeprecatedName: Bool {
     return deprecatedName != nil
   }
 
+  /// If this child is actually part of another child's history, links back
+  /// to the newest (that is, most current/non-deprecated) version of the
+  /// child. Nil if this is the newest version of the child.
+  public let newestChild: Child?
+
+  /// True if this child was created by a `Child.Refactoring`. Such children
+  /// are part of the compatibility layer and are therefore deprecated.
+  public var isHistorical: Bool {
+    newestChild != nil
+  }
+
+  /// Replaces the nodes in `newerChildPath` with their own `newerChildPath`s,
+  /// if any, to form a child path enitrely of non-historical nodes.
+  static private func makeNewestChild(from newerChild: Child?) -> Child? {
+    return newerChild?.newestChild ?? newerChild
+  }
+
+  private var newestName: String {
+    return newestChild?.name ?? name
+  }
+
   /// If the child ends with "token" in the kind, it's considered a token node.
   /// Grab the existing reference to that token from the global list.
   public var tokenKind: Token? {
@@ -244,19 +257,15 @@ public class Child: NodeChoiceConvertible {
     return AttributeListSyntax("@_spi(ExperimentalLanguageFeatures)").with(\.trailingTrivia, .newline)
   }
 
-  /// If a classification is passed, it specifies the color identifiers in
-  /// that subtree should inherit for syntax coloring. Must be a member of
-  /// ``SyntaxClassification``.
-  /// If `forceClassification` is also set to true, all child nodes (not only
-  /// identifiers) inherit the syntax classification.
   init(
     name: String,
     deprecatedName: String? = nil,
     kind: ChildKind,
     experimentalFeature: ExperimentalFeature? = nil,
     nameForDiagnostics: String? = nil,
     documentation: String? = nil,
-    isOptional: Bool = false
+    isOptional: Bool = false,
+    newerChild: Child? = nil
   ) {
     precondition(name.first?.isLowercase ?? true, "The first letter of a child’s name should be lowercase")
     precondition(
@@ -265,11 +274,63 @@ public class Child: NodeChoiceConvertible {
     )
     self.name = name
     self.deprecatedName = deprecatedName
+    self.newestChild = Self.makeNewestChild(from: newerChild)
     self.kind = kind
     self.experimentalFeature = experimentalFeature
     self.nameForDiagnostics = nameForDiagnostics
     self.documentationSummary = SwiftSyntax.Trivia.docCommentTrivia(from: documentation)
     self.documentationAbstract = String(documentation?.split(whereSeparator: \.isNewline).first ?? "")
     self.isOptional = isOptional
   }
+
+  /// Create a node that is a copy of the last node in `newerChildPath`, but
+  /// with modifications.
+  init(renamingTo replacementName: String? = nil, newerChild other: Child) {
+    self.name = replacementName ?? other.name
+    self.deprecatedName = nil
+    self.newestChild = Self.makeNewestChild(from: other)
+    self.kind = other.kind
+    self.experimentalFeature = other.experimentalFeature
+    self.nameForDiagnostics = other.nameForDiagnostics
+    self.documentationSummary = other.documentationSummary
+    self.documentationAbstract = other.documentationAbstract
+    self.isOptional = other.isOptional
+  }
+
+  /// Create a child for the unexpected nodes between two children (either or
+  /// both of which may be `nil`).
+  convenience init(forUnexpectedBetween earlier: Child?, and later: Child?, newerChild: Child? = nil) {
+    let name =
+      switch (earlier, later) {
+      case (nil, let later?):
+        "unexpectedBefore\(later.name.withFirstCharacterUppercased)"
+      case (let earlier?, nil):
+        "unexpectedAfter\(earlier.name.withFirstCharacterUppercased)"
+      case (let earlier?, let later?):
+        "unexpectedBetween\(earlier.name.withFirstCharacterUppercased)And\(later.name.withFirstCharacterUppercased)"
+      case (nil, nil):
+        fatalError("unexpected node has no siblings?")
+      }
+
+    self.init(
+      name: name,
+      deprecatedName: nil,  // deprecation of unexpected nodes is handled in CompatibilityLayer
+      kind: .collection(kind: .unexpectedNodes, collectionElementName: name.withFirstCharacterUppercased),
+      experimentalFeature: earlier?.experimentalFeature ?? later?.experimentalFeature,
+      nameForDiagnostics: nil,
+      documentation: nil,
+      isOptional: true,
+      newerChild: newerChild
+    )
+  }
+}
+
+extension Child: Hashable {
+  public static func == (lhs: Child, rhs: Child) -> Bool {
+    lhs === rhs
+  }
+
+  public func hash(into hasher: inout Hasher) {
+    hasher.combine(ObjectIdentifier(self))
+  }
 }

CodeGeneration/Sources/SyntaxSupport/CompatibilityLayer.swift

@@ -0,0 +1,132 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2014 - 2024 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 the list of Swift project authors
+//
+//===----------------------------------------------------------------------===//
+
+/// Computes and caches information about properties and initializers that ought to be generated for the compatibility layer.
+public struct CompatibilityLayer {
+  /// Deprecated members that the compatibility layer needs for each node.
+  private var deprecatedMembersByNode: [SyntaxNodeKind: DeprecatedMemberInfo] = [:]
+
+  /// Cache for `replacementChild(for:)`. Ensures that we don't create two different replacement children even
+  /// if we refactor the same child twice, so we can reliably equate and hash `Child` objects by object identity.
+  private var cachedReplacementChildren: [Child: Child?] = [:]
+
+  /// Returns the deprecated members that the compatibility layer needs for `node`.
+  public func deprecatedMembers(for node: LayoutNode) -> DeprecatedMemberInfo {
+    return deprecatedMembersByNode[node.kind] ?? DeprecatedMemberInfo()
+  }
+
+  internal init(nodes: [Node]) {
+    // This instance will be stored in a global that's used from multiple threads simultaneously, so it won't be safe
+    // to mutate once the initializer returns. We therefore do all the work to populate its tables up front, rather
+    // than computing it lazily on demand.
+    for node in nodes {
+      computeMembers(for: node)
+    }
+  }
+
+  private mutating func replacementChild(for newerChild: Child) -> Child? {
+    func make() -> Child? {
+      guard let deprecatedName = newerChild.deprecatedName else {
+        return nil
+      }
+
+      return Child(renamingTo: deprecatedName, newerChild: newerChild)
+    }
+
+    // Make sure we return the same instance even if we're called twice.
+    if cachedReplacementChildren[newerChild] == nil {
+      cachedReplacementChildren[newerChild] = make()
+    }
+    return cachedReplacementChildren[newerChild]!
+  }
+
+  private mutating func computeMembers(for node: Node) {
+    guard deprecatedMembersByNode[node.syntaxNodeKind] == nil, let layoutNode = node.layoutNode else {
+      return
+    }
+
+    // The results that will ultimately be saved into the DeprecatedMemberInfo.
+    var vars: [Child] = []
+    var initSignatures: [InitSignature] = []
+
+    // Temporary working state.
+    var children = layoutNode.children
+    var knownVars = Set(children)
+
+    func firstIndexOfChild(named targetName: String) -> Int {
+      guard let i = children.firstIndex(where: { $0.name == targetName }) else {
+        fatalError(
+          "couldn't find '\(targetName)' in current children of \(node.syntaxNodeKind.rawValue): \(String(reflecting: children.map(\.name)))"
+        )
+      }
+      return i
+    }
+
+    var unexpectedChildrenWithNewNames: Set<Child> = []
+
+    // First pass: Apply the changes explicitly specified in the change set.
+    for i in children.indices {
+      let currentName = children[i].name
+      guard let replacementChild = replacementChild(for: children[i]) else {
+        continue
+      }
+      children[i] = replacementChild
+
+      // Mark adjacent unexpected node children whose names have changed too.
+      if currentName != replacementChild.name {
+        unexpectedChildrenWithNewNames.insert(children[i - 1])
+        unexpectedChildrenWithNewNames.insert(children[i + 1])
+      }
+    }
+
+    // Second pass: Update unexpected node children adjacent to those changes whose names have probably changed.
+    for unexpectedChild in unexpectedChildrenWithNewNames {
+      precondition(unexpectedChild.isUnexpectedNodes)
+      let i = firstIndexOfChild(named: unexpectedChild.name)
+
+      let earlier = children[checked: i - 1]
+      let later = children[checked: i + 1]
+      precondition(!(earlier?.isUnexpectedNodes ?? false) && !(later?.isUnexpectedNodes ?? false))
+
+      let newChild = Child(forUnexpectedBetween: earlier, and: later, newerChild: unexpectedChild)
+      precondition(newChild.name != unexpectedChild.name)
+      precondition(!children.contains { $0.name == newChild.name })
+
+      children[i] = newChild
+    }
+
+    // Third pass: Append newly-created children to vars. We do this now so that changes from the first two passes are properly interleaved, preserving source order.
+    vars += children.filter { knownVars.insert($0).inserted }
+
+    initSignatures.append(InitSignature(children: children))
+
+    deprecatedMembersByNode[node.syntaxNodeKind] = DeprecatedMemberInfo(vars: vars, inits: initSignatures)
+  }
+}
+
+/// Describes the deprecated members of a given type that the compatibility layer ought to provide.
+public struct DeprecatedMemberInfo {
+  /// Properties that are needed in the compatibility layer, in the order they ought to appear in the generated file.
+  public var vars: [Child] = []
+
+  /// Initializer signatures that are needed in the compatibility layer, in the order they ought to appear in the generated file.
+  public var inits: [InitSignature] = []
+}
+
+extension Array {
+  /// Returns `nil` if `i` is out of bounds, or the indicated element otherwise.
+  fileprivate subscript(checked i: Index) -> Element? {
+    get {
+      return indices.contains(i) ? self[i] : nil
+    }
+  }
+}

CodeGeneration/Sources/SyntaxSupport/Node.swift

@@ -135,59 +135,8 @@ public class Node: NodeChoiceConvertible {
     self.documentation = SwiftSyntax.Trivia.docCommentTrivia(from: documentation)
     self.parserFunction = parserFunction
 
-    let childrenWithUnexpected: [Child]
-    if children.isEmpty {
-      childrenWithUnexpected = [
-        Child(
-          name: "unexpected",
-          kind: .collection(kind: .unexpectedNodes, collectionElementName: "Unexpected"),
-          isOptional: true
-        )
-      ]
-    } else {
-      // Add implicitly generated UnexpectedNodes children between
-      // any two defined children
-      childrenWithUnexpected =
-        children.enumerated().flatMap { (i, child) -> [Child] in
-          let childName = child.name.withFirstCharacterUppercased
-
-          let unexpectedName: String
-          let unexpectedDeprecatedName: String?
-
-          if i == 0 {
-            unexpectedName = "unexpectedBefore\(childName)"
-            unexpectedDeprecatedName = child.deprecatedName.map { "unexpectedBefore\($0.withFirstCharacterUppercased)" }
-          } else {
-            unexpectedName = "unexpectedBetween\(children[i - 1].name.withFirstCharacterUppercased)And\(childName)"
-            if let deprecatedName = children[i - 1].deprecatedName?.withFirstCharacterUppercased {
-              unexpectedDeprecatedName =
-                "unexpectedBetween\(deprecatedName)And\(child.deprecatedName?.withFirstCharacterUppercased ?? childName)"
-            } else if let deprecatedName = child.deprecatedName?.withFirstCharacterUppercased {
-              unexpectedDeprecatedName =
-                "unexpectedBetween\(children[i - 1].name.withFirstCharacterUppercased)And\(deprecatedName)"
-            } else {
-              unexpectedDeprecatedName = nil
-            }
-          }
-          let unexpectedBefore = Child(
-            name: unexpectedName,
-            deprecatedName: unexpectedDeprecatedName,
-            kind: .collection(kind: .unexpectedNodes, collectionElementName: unexpectedName),
-            isOptional: true
-          )
-          return [unexpectedBefore, child]
-        } + [
-          Child(
-            name: "unexpectedAfter\(children.last!.name.withFirstCharacterUppercased)",
-            deprecatedName: children.last!.deprecatedName.map { "unexpectedAfter\($0.withFirstCharacterUppercased)" },
-            kind: .collection(
-              kind: .unexpectedNodes,
-              collectionElementName: "UnexpectedAfter\(children.last!.name.withFirstCharacterUppercased)"
-            ),
-            isOptional: true
-          )
-        ]
-    }
+    let childrenWithUnexpected = kind.isBase ? children : interleaveUnexpectedChildren(children)
+
     self.data = .layout(children: childrenWithUnexpected, traits: traits)
   }
 
@@ -425,3 +374,12 @@ fileprivate extension Child {
     }
   }
 }
+
+fileprivate func interleaveUnexpectedChildren(_ children: [Child]) -> [Child] {
+  let liftedChildren = children.lazy.map(Optional.some)
+  let pairedChildren = zip([nil] + liftedChildren, liftedChildren + [nil])
+
+  return pairedChildren.flatMap { earlier, later in
+    [earlier, Child(forUnexpectedBetween: earlier, and: later)].compactMap { $0 }
+  }
+}

CodeGeneration/Sources/SyntaxSupport/SyntaxNodes.swift

@@ -35,3 +35,5 @@ public let SYNTAX_NODE_MAP: [SyntaxNodeKind: Node] = Dictionary(
 )
 
 public let NON_BASE_SYNTAX_NODES = SYNTAX_NODES.filter { !$0.kind.isBase }
+
+public let SYNTAX_COMPATIBILITY_LAYER = CompatibilityLayer(nodes: SYNTAX_NODES)