Merge pull request #2952 from MAJKFL/swift-lexical-lookup-rfc

[RFC][SwiftLexicalLookup] Make unqualified name lookup entry-point public

Author: MAJKFL

Release Notes/602.md

@@ -7,6 +7,11 @@
   - Pull Request: https://github.com/swiftlang/swift-syntax/pull/2981
   - Migration steps: None required. The new `category` property has optional type, and there is a default implementation that returns `nil`. Types that conform to `DiagnosticMessage` can choose to implement this property and provide a category when appropriate.
 
+- `SwiftLexicalLookup` - A new Swift unqualified lookup library
+  - Description: The library provides a new Swift unqualified lookup implementation detached from the compiler and accessible to outside clients. The query is stateless and can be directly run on swift-syntax syntax tree, with any syntax node functioning as an entry point. It produces an enum-based data structure as a result that partitions collected names based on the lexical scope of introduction. 
+  - Pull Request: https://github.com/swiftlang/swift-syntax/pull/2952
+  - Notes: The library follows the behavior of the compiler implementation with some minor differences, such as a different way of handling dollar identifiers `$x` and generic parameters inside extensions. Furthermore, in the future, once the compiler adopts `SwiftLexicalLookup` and it becomes the canonical implementation, results produced by the query will be guaranteed to be correct.
+
 ## API Behavior Changes
 
 ## Deprecations

Sources/SwiftLexicalLookup/IdentifiableSyntax.swift

@@ -13,50 +13,50 @@
 import SwiftSyntax
 
 /// Syntax node that can be refered to with an identifier.
-@_spi(Experimental) public protocol IdentifiableSyntax: SyntaxProtocol {
+protocol IdentifiableSyntax: SyntaxProtocol {
   var identifier: TokenSyntax { get }
 }
 
-@_spi(Experimental) extension IdentifierPatternSyntax: IdentifiableSyntax {}
+extension IdentifierPatternSyntax: IdentifiableSyntax {}
 
-@_spi(Experimental) extension ClosureParameterSyntax: IdentifiableSyntax {
-  @_spi(Experimental) public var identifier: TokenSyntax {
+extension ClosureParameterSyntax: IdentifiableSyntax {
+  var identifier: TokenSyntax {
     secondName ?? firstName
   }
 }
 
-@_spi(Experimental) extension FunctionParameterSyntax: IdentifiableSyntax {
-  @_spi(Experimental) public var identifier: TokenSyntax {
+extension FunctionParameterSyntax: IdentifiableSyntax {
+  var identifier: TokenSyntax {
     secondName ?? firstName
   }
 }
 
-@_spi(Experimental) extension ClosureShorthandParameterSyntax: IdentifiableSyntax {
-  @_spi(Experimental) public var identifier: TokenSyntax {
+extension ClosureShorthandParameterSyntax: IdentifiableSyntax {
+  var identifier: TokenSyntax {
     name
   }
 }
 
-@_spi(Experimental) extension ClosureCaptureSyntax: IdentifiableSyntax {
-  @_spi(Experimental) public var identifier: TokenSyntax {
+extension ClosureCaptureSyntax: IdentifiableSyntax {
+  var identifier: TokenSyntax {
     name
   }
 }
 
-@_spi(Experimental) extension AccessorParametersSyntax: IdentifiableSyntax {
-  @_spi(Experimental) public var identifier: TokenSyntax {
+extension AccessorParametersSyntax: IdentifiableSyntax {
+  var identifier: TokenSyntax {
     name
   }
 }
 
-@_spi(Experimental) extension GenericParameterSyntax: IdentifiableSyntax {
-  @_spi(Experimental) public var identifier: TokenSyntax {
+extension GenericParameterSyntax: IdentifiableSyntax {
+  var identifier: TokenSyntax {
     name
   }
 }
 
-@_spi(Experimental) extension PrimaryAssociatedTypeSyntax: IdentifiableSyntax {
-  @_spi(Experimental) public var identifier: TokenSyntax {
+extension PrimaryAssociatedTypeSyntax: IdentifiableSyntax {
+  var identifier: TokenSyntax {
     name
   }
 }

Sources/SwiftLexicalLookup/LookupConfig.swift

@@ -12,7 +12,7 @@
 
 import SwiftIfConfig
 
-@_spi(Experimental) public struct LookupConfig {
+public struct LookupConfig {
   /// Specifies whether lookup should finish in the closest sequential scope.
   ///
   /// ### Example
@@ -32,14 +32,14 @@ import SwiftIfConfig
   /// function parameter and the `a` declaration from `class X` member block.
   /// If `finishInSequentialScope` would be set to `false`, the only name
   /// returned by lookup would be the `a` declaration from inside function body.
-  @_spi(Experimental) public var finishInSequentialScope: Bool
-  @_spi(Experimental) public var configuredRegions: ConfiguredRegions?
+  public var finishInSequentialScope: Bool
+  public var configuredRegions: ConfiguredRegions?
 
   /// Creates a new lookup configuration.
   ///
   /// - `finishInSequentialScope` - specifies whether lookup should finish
   ///   in the closest sequential scope. `false` by default.
-  @_spi(Experimental) public init(
+  public init(
     finishInSequentialScope: Bool = false,
     configuredRegions: ConfiguredRegions? = nil
   ) {

Sources/SwiftLexicalLookup/LookupName.swift

@@ -13,15 +13,18 @@
 import SwiftSyntax
 
 /// An entity that is implicitly declared based on the syntactic structure of the program.
-@_spi(Experimental) public enum ImplicitDecl {
+public enum ImplicitDecl {
   /// `self` keyword representing object instance.
-  /// Could be associated with type declaration, extension,
-  /// or closure captures. Introduced at function edge.
-  case `self`(DeclSyntaxProtocol)
+  /// Introduced at member boundary.
+  /// Associated syntax node could be: `FunctionDeclSyntax`,
+  /// `AccessorDeclSyntax`, `SubscriptDeclSyntax`,
+  /// `DeinitializerDeclSyntax`, or `InitializerDeclSyntax`.
+  case `self`(DeclSyntax)
   /// `Self` keyword representing object type.
-  /// Could be associated with type declaration or extension.
-  case `Self`(DeclSyntaxProtocol)
-  /// `error` value caught by a `catch`
+  /// Associated syntax node could be: `ExtensionDeclSyntax`,
+  /// or `ProtocolDeclSyntax`.
+  case `Self`(DeclSyntax)
+  /// `error` available by default inside `catch`
   /// block that does not specify a catch pattern.
   case error(CatchClauseSyntax)
   /// `newValue` available by default inside `set` and `willSet`.
@@ -30,7 +33,7 @@ import SwiftSyntax
   case oldValue(AccessorDeclSyntax)
 
   /// Syntax associated with this name.
-  @_spi(Experimental) public var syntax: SyntaxProtocol {
+  public var syntax: SyntaxProtocol {
     switch self {
     case .self(let syntax):
       return syntax
@@ -46,7 +49,7 @@ import SwiftSyntax
   }
 
   /// The name of the implicit declaration.
-  private var name: StaticString {
+  public var name: StaticString {
     switch self {
     case .self:
       return "self"
@@ -85,12 +88,12 @@ import SwiftSyntax
   /// ```
   /// `self` and `Self` identifers override implicit `self` and `Self` introduced by
   /// the `Foo` class declaration.
-  var identifier: Identifier {
+  public var identifier: Identifier {
     Identifier(canonicalName: name)
   }
 
   /// Position of this implicit name.
-  @_spi(Experimental) public var position: AbsolutePosition {
+  public var position: AbsolutePosition {
     switch self {
     case .self(let declSyntax):
       switch Syntax(declSyntax).as(SyntaxEnum.self) {
@@ -128,17 +131,15 @@ import SwiftSyntax
   }
 }
 
-@_spi(Experimental) public enum LookupName {
+public enum LookupName {
   /// Identifier associated with the name.
   /// Could be an identifier of a variable, function or closure parameter and more.
-  case identifier(IdentifiableSyntax, accessibleAfter: AbsolutePosition?)
+  case identifier(Syntax, accessibleAfter: AbsolutePosition?)
   /// Declaration associated with the name.
   /// Could be class, struct, actor, protocol, function and more.
-  case declaration(NamedDeclSyntax)
+  case declaration(Syntax)
   /// Name introduced implicitly by certain syntax nodes.
   case implicit(ImplicitDecl)
-  /// Dollar identifier introduced by a closure without parameters.
-  case dollarIdentifier(ClosureExprSyntax, strRepresentation: String)
   /// Represents equivalent names grouped together.
   /// - Important: The array should be non-empty.
   ///
@@ -154,32 +155,28 @@ import SwiftSyntax
   case equivalentNames([LookupName])
 
   /// Syntax associated with this name.
-  @_spi(Experimental) public var syntax: SyntaxProtocol {
+  public var syntax: SyntaxProtocol {
     switch self {
     case .identifier(let syntax, _):
       return syntax
     case .declaration(let syntax):
       return syntax
     case .implicit(let implicitName):
       return implicitName.syntax
-    case .dollarIdentifier(let closureExpr, _):
-      return closureExpr
     case .equivalentNames(let names):
       return names.first!.syntax
     }
   }
 
   /// Identifier used for name comparison.
-  @_spi(Experimental) public var identifier: Identifier? {
+  public var identifier: Identifier {
     switch self {
     case .identifier(let syntax, _):
-      return Identifier(syntax.identifier)
+      return Identifier((syntax.asProtocol(SyntaxProtocol.self) as! IdentifiableSyntax).identifier)!
     case .declaration(let syntax):
-      return Identifier(syntax.name)
+      return Identifier((syntax.asProtocol(SyntaxProtocol.self) as! NamedDeclSyntax).name)!
     case .implicit(let kind):
       return kind.identifier
-    case .dollarIdentifier(_, strRepresentation: _):
-      return nil
     case .equivalentNames(let names):
       return names.first!.identifier
     }
@@ -192,16 +189,15 @@ import SwiftSyntax
   /// Such cases are function parameters (as they can
   /// contain two identifiers) and function declarations (where name
   /// is precided by access modifiers and `func` keyword).
-  @_spi(Experimental) public var position: AbsolutePosition {
+  public var position: AbsolutePosition {
     switch self {
     case .identifier(let syntax, _):
-      return syntax.identifier.positionAfterSkippingLeadingTrivia
+      return (syntax.asProtocol(SyntaxProtocol.self) as! IdentifiableSyntax).identifier
+        .positionAfterSkippingLeadingTrivia
     case .declaration(let syntax):
-      return syntax.name.positionAfterSkippingLeadingTrivia
+      return (syntax.asProtocol(SyntaxProtocol.self) as! NamedDeclSyntax).name.positionAfterSkippingLeadingTrivia
     case .implicit(let implicitName):
       return implicitName.position
-    case .dollarIdentifier(let closureExpr, _):
-      return closureExpr.positionAfterSkippingLeadingTrivia
     case .equivalentNames(let names):
       return names.first!.position
     }
@@ -226,13 +222,7 @@ import SwiftSyntax
 
   func refersTo(_ otherIdentifier: Identifier?) -> Bool {
     guard let otherIdentifier else { return true }
-
-    switch self {
-    case .dollarIdentifier(_, let strRepresentation):
-      return strRepresentation == otherIdentifier.name
-    default:
-      return identifier == otherIdentifier
-    }
+    return identifier == otherIdentifier
   }
 
   /// Extracts names introduced by the given `syntax` structure.
@@ -305,22 +295,22 @@ import SwiftSyntax
       return []
     }
 
-    return [.identifier(identifiable, accessibleAfter: accessibleAfter)]
+    return [.identifier(Syntax(identifiable), accessibleAfter: accessibleAfter)]
   }
 
   /// Extracts name introduced by `NamedDeclSyntax` node.
   private static func handle(
     namedDecl: NamedDeclSyntax,
     accessibleAfter: AbsolutePosition? = nil
   ) -> [LookupName] {
-    [.declaration(namedDecl)]
+    [.declaration(Syntax(namedDecl))]
   }
 
   /// Debug description of this lookup name.
-  @_spi(Experimental) public var debugDescription: String {
+  public var debugDescription: String {
     let sourceLocationConverter = SourceLocationConverter(fileName: "", tree: syntax.root)
     let location = sourceLocationConverter.location(for: position)
-    let strName = (identifier?.name ?? "NO-NAME") + " at: \(location.line):\(location.column)"
+    let strName = identifier.name + " at: \(location.line):\(location.column)"
 
     switch self {
     case .identifier:
@@ -336,8 +326,6 @@ import SwiftSyntax
       return "declaration: \(strName)"
     case .implicit:
       return "implicit: \(strName)"
-    case .dollarIdentifier(_, strRepresentation: let str):
-      return "dollarIdentifier: \(str)"
     case .equivalentNames(let names):
       return "Composite name: [ \(names.map(\.debugDescription).joined(separator: ", ")) ]"
     }