[Macros] Introduce AbstractSourceLocation and its APIs

Introduce `AbstractSourceLocation` as a macro-focused API that
uses opaque syntax rather than direct values. Update the
MacroExpansionContext APIs for location access to use this type,
leaving the old versions in place to allow for some staging for
clients.

This aligns the location APIs with what is proposed in SE-0382.

Author: DougGregor

Sources/SwiftSyntaxMacros/AbstractSourceLocation.swift

@@ -0,0 +1,25 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2014 - 2023 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
+//
+//===----------------------------------------------------------------------===//
+
+import SwiftSyntax
+
+/// Abstractly represents a source location in the macro.
+public struct AbstractSourceLocation {
+  /// A primary expression that represents the file and is `ExpressibleByStringLiteral`.
+  public let file: ExprSyntax
+
+  /// A primary expression that represents the line and is `ExpressibleByIntegerLiteral`.
+  public let line: ExprSyntax
+
+  /// A primary expression that represents the column and is `ExpressibleByIntegerLiteral`.
+  public let column: ExprSyntax
+}

Sources/SwiftSyntaxMacros/CMakeLists.txt

@@ -19,6 +19,7 @@ add_swift_host_library(SwiftSyntaxMacros
   MacroProtocols/MemberMacro.swift
   MacroProtocols/PeerMacro.swift
 
+  AbstractSourceLocation.swift
   BasicMacroExpansionContext.swift
   MacroExpansionContext.swift
   MacroSystem.swift

Sources/SwiftSyntaxMacros/MacroExpansionContext.swift

@@ -10,8 +10,9 @@
 //
 //===----------------------------------------------------------------------===//
 
-import SwiftSyntax
 import SwiftDiagnostics
+import SwiftSyntax
+import SwiftSyntaxBuilder
 
 /// Interface to extract information about the context in which a given
 /// macro is expanded.
@@ -41,11 +42,31 @@ public protocol MacroExpansionContext: AnyObject {
   /// - Returns: the source location within the given node, or `nil` if the
   ///   given syntax node is not rooted in a source file that the macro
   ///   expansion context knows about.
+  @available(*, deprecated, message: "Please use AbstractSourceLocation version")
   func location<Node: SyntaxProtocol>(
     of node: Node,
     at position: PositionInSyntaxNode,
     filePathMode: SourceLocationFilePathMode
   ) -> SourceLocation?
+
+  /// Retrieve a source location for the given syntax node.
+  ///
+  /// - Parameters:
+  ///   - node: The syntax node whose source location to produce.
+  ///   - position: The position within the syntax node for the resulting
+  ///     location.
+  ///   - filePathMode: How the file name contained in the source location is
+  ///     formed.
+  ///
+  /// - Returns: the source location within the given node, or `nil` if the
+  ///   given syntax node is not rooted in a source file that the macro
+  ///   expansion context knows about.
+  @_disfavoredOverload
+  func location<Node: SyntaxProtocol>(
+    of node: Node,
+    at position: PositionInSyntaxNode,
+    filePathMode: SourceLocationFilePathMode
+  ) -> AbstractSourceLocation?
 }
 
 extension MacroExpansionContext {
@@ -58,11 +79,64 @@ extension MacroExpansionContext {
   /// - Returns: the source location within the given node, or `nil` if the
   ///   given syntax node is not rooted in a source file that the macro
   ///   expansion context knows about.
+  @available(*, deprecated, message: "Please use AbstractSourceLocation version")
   public func location<Node: SyntaxProtocol>(
     of node: Node
   ) -> SourceLocation? {
     return location(of: node, at: .afterLeadingTrivia, filePathMode: .fileID)
   }
+
+  /// Retrieve a source location for the given syntax node's starting token
+  /// (after leading trivia) using file naming according to `#fileID`.
+  ///
+  /// - Parameters:
+  ///   - node: The syntax node whose source location to produce.
+  ///
+  /// - Returns: the source location within the given node, or `nil` if the
+  ///   given syntax node is not rooted in a source file that the macro
+  ///   expansion context knows about.
+  @_disfavoredOverload
+  public func location<Node: SyntaxProtocol>(
+    of node: Node
+  ) -> AbstractSourceLocation? {
+    return location(of: node, at: .afterLeadingTrivia, filePathMode: .fileID)
+  }
+}
+
+extension MacroExpansionContext {
+  /// Retrieve a source location for the given syntax node.
+  ///
+  /// - Parameters:
+  ///   - node: The syntax node whose source location to produce.
+  ///   - position: The position within the syntax node for the resulting
+  ///     location.
+  ///   - filePathMode: How the file name contained in the source location is
+  ///     formed.
+  ///
+  /// - Returns: the source location within the given node, or `nil` if the
+  ///   given syntax node is not rooted in a source file that the macro
+  ///   expansion context knows about.
+  @_disfavoredOverload
+  @available(*, deprecated, message: "Please use AbstractSourceLocation version")
+  public func location<Node: SyntaxProtocol>(
+    of node: Node,
+    at position: PositionInSyntaxNode,
+    filePathMode: SourceLocationFilePathMode
+  ) -> AbstractSourceLocation? {
+    guard let sourceLoc: SourceLocation = location(of: node, at: position, filePathMode: filePathMode),
+      let file = sourceLoc.file,
+      let line = sourceLoc.line,
+      let column = sourceLoc.column
+    else {
+      return nil
+    }
+
+    return AbstractSourceLocation(
+      file: "\(literal: file)",
+      line: "\(literal: line)",
+      column: "\(literal: column)"
+    )
+  }
 }
 
 /// Diagnostic message used for thrown errors.

Tests/SwiftSyntaxMacrosTest/MacroSystemTests.swift

@@ -130,17 +130,15 @@ public struct ColumnMacro: ExpressionMacro {
     of macro: Node,
     in context: Context
   ) throws -> ExprSyntax {
-    guard let sourceLoc = context.location(of: macro),
-      let column = sourceLoc.column
+    guard let sourceLoc: AbstractSourceLocation = context.location(of: macro)
     else {
       throw CustomError.message("can't find location for macro")
     }
 
-    let fileLiteral: ExprSyntax = "\(literal: column)"
     if let leadingTrivia = macro.leadingTrivia {
-      return fileLiteral.with(\.leadingTrivia, leadingTrivia)
+      return sourceLoc.column.with(\.leadingTrivia, leadingTrivia)
     }
-    return fileLiteral
+    return sourceLoc.column
   }
 }
 
@@ -152,17 +150,15 @@ public struct FileIDMacro: ExpressionMacro {
     of macro: Node,
     in context: Context
   ) throws -> ExprSyntax {
-    guard let sourceLoc = context.location(of: macro),
-      let fileID = sourceLoc.file
+    guard let sourceLoc: AbstractSourceLocation = context.location(of: macro)
     else {
       throw CustomError.message("can't find location for macro")
     }
 
-    let fileLiteral: ExprSyntax = "\(literal: fileID)"
     if let leadingTrivia = macro.leadingTrivia {
-      return fileLiteral.with(\.leadingTrivia, leadingTrivia)
+      return sourceLoc.file.with(\.leadingTrivia, leadingTrivia)
     }
-    return fileLiteral
+    return sourceLoc.file
   }
 }