Add new result structure using LookupResult enum array.

Author: MAJKFL

Sources/SwiftLexicalLookup/LookupName.swift

@@ -39,7 +39,7 @@ import SwiftSyntax
       syntax.name.text
     }
   }
-  
+
   /// Point, after which the name is available in scope.
   /// If set to `nil`, the name is available at any point in scope.
   var accessibleAfter: AbsolutePosition? {
@@ -97,14 +97,15 @@ import SwiftSyntax
   }
 
   /// Extracts name introduced by `IdentifiableSyntax` node.
-  private static func handle(identifiable: IdentifiableSyntax, accessibleAfter: AbsolutePosition? = nil) -> [LookupName] {
+  private static func handle(identifiable: IdentifiableSyntax, accessibleAfter: AbsolutePosition? = nil) -> [LookupName]
+  {
     if identifiable.identifier.text != "_" {
       return [.identifier(identifiable, accessibleAfter: accessibleAfter)]
     } else {
       return []
     }
   }
-  
+
   /// Extracts name introduced by `NamedDeclSyntax` node.
   private static func handle(namedDecl: NamedDeclSyntax, accessibleAfter: AbsolutePosition? = nil) -> [LookupName] {
     [.declaration(namedDecl, accessibleAfter: accessibleAfter)]

Sources/SwiftLexicalLookup/LookupResult.swift

@@ -0,0 +1,35 @@
+//===----------------------------------------------------------------------===//
+//
+// 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
+//
+//===----------------------------------------------------------------------===//
+
+import SwiftSyntax
+
+/// Represents resul
+@_spi(Experimental) public enum LookupResult {
+  /// Scope and the names that matched lookup.
+  case fromScope(ScopeSyntax, withNames: [LookupName])
+
+  /// Associated scope.
+  @_spi(Experimental) public var scope: ScopeSyntax? {
+    switch self {
+    case .fromScope(let scopeSyntax, _):
+      scopeSyntax
+    }
+  }
+
+  /// Names that matched lookup.
+  @_spi(Experimental) public var names: [LookupName] {
+    switch self {
+    case .fromScope(_, let names):
+      names
+    }
+  }
+}

Sources/SwiftLexicalLookup/ScopeImplementations.swift

@@ -23,28 +23,28 @@ extension SyntaxProtocol {
   }
 }
 
-extension SourceFileSyntax: ScopeSyntax {
-  var introducedNames: [LookupName] {
+@_spi(Experimental) extension SourceFileSyntax: ScopeSyntax {
+  public var introducedNames: [LookupName] {
     []
   }
 }
 
-extension CodeBlockSyntax: ScopeSyntax {
-  var introducedNames: [LookupName] {
+@_spi(Experimental) extension CodeBlockSyntax: ScopeSyntax {
+  public var introducedNames: [LookupName] {
     statements.flatMap { codeBlockItem in
-      LookupName.getNames(from: codeBlockItem.item, accessibleAfter: codeBlockItem.item.endPosition)
+      LookupName.getNames(from: codeBlockItem.item, accessibleAfter: codeBlockItem.endPosition)
     }
   }
 }
 
-extension ForStmtSyntax: ScopeSyntax {
-  var introducedNames: [LookupName] {
+@_spi(Experimental) extension ForStmtSyntax: ScopeSyntax {
+  public var introducedNames: [LookupName] {
     LookupName.getNames(from: pattern)
   }
 }
 
-extension ClosureExprSyntax: ScopeSyntax {
-  var introducedNames: [LookupName] {
+@_spi(Experimental) extension ClosureExprSyntax: ScopeSyntax {
+  public var introducedNames: [LookupName] {
     signature?.parameterClause?.children(viewMode: .sourceAccurate).flatMap { parameter in
       if let parameterList = parameter.as(ClosureParameterListSyntax.self) {
         parameterList.children(viewMode: .sourceAccurate).flatMap { parameter in
@@ -57,16 +57,16 @@ extension ClosureExprSyntax: ScopeSyntax {
   }
 }
 
-extension WhileStmtSyntax: ScopeSyntax {
-  var introducedNames: [LookupName] {
+@_spi(Experimental) extension WhileStmtSyntax: ScopeSyntax {
+  public var introducedNames: [LookupName] {
     conditions.flatMap { element in
       LookupName.getNames(from: element.condition)
     }
   }
 }
 
-extension IfExprSyntax: ScopeSyntax {
-  var parentScope: ScopeSyntax? {
+@_spi(Experimental) extension IfExprSyntax: ScopeSyntax {
+  public var parentScope: ScopeSyntax? {
     getParent(for: self.parent, previousIfElse: self.elseKeyword == nil)
   }
 
@@ -85,13 +85,13 @@ extension IfExprSyntax: ScopeSyntax {
     }
   }
 
-  var introducedNames: [LookupName] {
+  public var introducedNames: [LookupName] {
     conditions.flatMap { element in
-      LookupName.getNames(from: element.condition, accessibleAfter: element.condition.endPosition)
+      LookupName.getNames(from: element.condition, accessibleAfter: element.endPosition)
     }
   }
 
-  func lookup(for name: String, at syntax: SyntaxProtocol) -> [LookupName] {
+  public func lookup(for name: String?, at syntax: SyntaxProtocol) -> [LookupResult] {
     if let elseBody, elseBody.position <= syntax.position, elseBody.endPosition >= syntax.position {
       parentScope?.lookup(for: name, at: syntax) ?? []
     } else {
@@ -100,8 +100,8 @@ extension IfExprSyntax: ScopeSyntax {
   }
 }
 
-extension MemberBlockSyntax: ScopeSyntax {
-  var introducedNames: [LookupName] {
+@_spi(Experimental) extension MemberBlockSyntax: ScopeSyntax {
+  public var introducedNames: [LookupName] {
     members.flatMap { member in
       LookupName.getNames(from: member.decl)
     }

Sources/SwiftLexicalLookup/ScopeSyntax.swift

@@ -15,9 +15,10 @@ import SwiftSyntax
 extension SyntaxProtocol {
   /// Returns all names that `for` refers to at this syntax node.
   ///
-  /// - Returns: An array of names referred to by `for` at this syntax node,
-  /// ordered by visibility. The order is from the innermost to the outermost
-  /// scope, and within each scope, names are ordered by their introduction
+  /// - Returns: An array of `LookupResult` for name `for` at this syntax node,
+  /// ordered by visibility. If set to `nil`, returns all available names ordered by visibility.
+  /// The order is from the innermost to the outermost scope,
+  /// and within each result, names are ordered by their introduction
   /// in the source code.
   ///
   /// Example usage:
@@ -41,40 +42,50 @@ extension SyntaxProtocol {
   /// declaration, followed by the first function name, and then the second function name,
   /// in this exact order. The constant declaration within the function body is omitted
   /// due to the ordering rules that prioritize visibility within the function body.
-  @_spi(Experimental) public func lookup(for name: String) -> [LookupName] {
+  @_spi(Experimental) public func lookup(for name: String?) -> [LookupResult] {
     scope?.lookup(for: name, at: self) ?? []
   }
 }
 
-protocol ScopeSyntax: SyntaxProtocol {
+@_spi(Experimental) public protocol ScopeSyntax: SyntaxProtocol {
   /// Parent of this scope, or `nil` if it is the root.
   var parentScope: ScopeSyntax? { get }
   /// Names found in this scope. Ordered from first to last introduced.
   var introducedNames: [LookupName] { get }
   /// Finds all declarations `name` refers to. `at` specifies the node lookup was triggered with.
-  func lookup(for name: String, at syntax: SyntaxProtocol) -> [LookupName]
+  /// If `name` set to `nil`, returns all available names at the given node.
+  func lookup(for name: String?, at syntax: SyntaxProtocol) -> [LookupResult]
 }
 
-extension ScopeSyntax {
-  var parentScope: ScopeSyntax? {
+@_spi(Experimental) extension ScopeSyntax {
+  public var parentScope: ScopeSyntax? {
     self.parent?.scope
   }
-  
-  /// Returns all names introduced in this scope that `name` refers to and
-  /// is accessible at given syntax node then passes lookup to the parent.
-  func lookup(for name: String, at syntax: SyntaxProtocol) -> [LookupName] {
+
+  /// Returns `LookupResult` of all names introduced in this scope that `name`
+  /// refers to and is accessible at given syntax node then passes lookup to the parent.
+  /// If `name` set to `nil`, returns all available names at the given node.
+  public func lookup(for name: String?, at syntax: SyntaxProtocol) -> [LookupResult] {
     defaultLookupImplementation(for: name, at: syntax)
   }
 
-  /// Returns all names introduced in this scope that `name` refers to and
-  /// is accessible at given syntax node then passes lookup to the parent.
-  func defaultLookupImplementation(
-    for name: String,
+  /// Returns `LookupResult` of all names introduced in this scope that `name`
+  /// refers to and is accessible at given syntax node then passes lookup to the parent.
+  /// If `name` set to `nil`, returns all available names at the given node.
+  public func defaultLookupImplementation(
+    for name: String?,
     at syntax: SyntaxProtocol
-  ) -> [LookupName] {
-    introducedNames
+  ) -> [LookupResult] {
+    let filteredNames =
+      introducedNames
       .filter { introducedName in
-        introducedName.isAccessible(at: syntax) && introducedName.refersTo(name)
-      } + (parentScope?.lookup(for: name, at: syntax) ?? [])
+        introducedName.isAccessible(at: syntax) && (name == nil || introducedName.refersTo(name!))
+      }
+
+    if filteredNames.isEmpty {
+      return parentScope?.lookup(for: name, at: syntax) ?? []
+    } else {
+      return [.fromScope(self, withNames: filteredNames)] + (parentScope?.lookup(for: name, at: syntax) ?? [])
+    }
   }
 }

Tests/SwiftLexicalLookupTest/Assertions.swift

@@ -53,12 +53,31 @@ enum MarkerExpectation {
   }
 }
 
+/// Used to define
+enum ResultExpectation {
+  case fromScope(ScopeSyntax.Type, expectedNames: [String])
+
+  var expectedNames: [String] {
+    switch self {
+    case .fromScope(_, let expectedNames):
+      expectedNames
+    }
+  }
+
+  static func == (lhs: ResultExpectation, rhs: LookupResult) -> Bool {
+    switch (lhs, rhs) {
+    case (.fromScope, .fromScope):
+      return true
+    }
+  }
+}
+
 /// `methodUnderTest` is called with the token at every position marker in the keys of `expected`.
 /// It then asserts that the positions of the syntax nodes returned by `methodUnderTest` are the values in `expected`.
 /// It also checks whether result types match rules specified in `expectedResultTypes`.
 func assertLexicalScopeQuery(
   source: String,
-  methodUnderTest: (TokenSyntax) -> ([SyntaxProtocol?]),
+  methodUnderTest: (String, TokenSyntax) -> ([SyntaxProtocol?]),
   expected: [String: [String?]],
   expectedResultTypes: MarkerExpectation = .none
 ) {
@@ -80,7 +99,7 @@ func assertLexicalScopeQuery(
     }
 
     // Execute the tested method
-    let result = methodUnderTest(testArgument)
+    let result = methodUnderTest(marker, testArgument)
 
     // Extract the expected results for the test argument
     let expectedPositions: [AbsolutePosition?] = expectedMarkers.map { expectedMarker in
@@ -135,17 +154,48 @@ func assertLexicalScopeQuery(
 /// It also checks whether result types match rules specified in `expectedResultTypes`.
 func assertLexicalNameLookup(
   source: String,
-  references: [String: [String]],
-  expectedResultTypes: MarkerExpectation = .none
+  references: [String: [ResultExpectation]],
+  expectedResultTypes: MarkerExpectation = .none,
+  useNilAsTheParameter: Bool = false
 ) {
   assertLexicalScopeQuery(
     source: source,
-    methodUnderTest: { argument in
-      return argument.lookup(for: argument.text).map { lookUpResult in
-        lookUpResult.syntax
+    methodUnderTest: { marker, argument in
+      let result = argument.lookup(for: useNilAsTheParameter ? nil : argument.text)
+
+      guard let expectedValues = references[marker] else {
+        XCTFail("For marker \(marker), couldn't find expectation")
+        return []
+      }
+
+      for (actual, expected) in zip(result, expectedValues) {
+        XCTAssert(
+          expected == actual,
+          "For marker \(marker), expected actual result \(actual) doesn't match expected \(expected)"
+        )
+
+        switch actual {
+        case .fromScope(let scope, withNames: _):
+          if case .fromScope(let expectedType, expectedNames: _) = expected {
+            XCTAssert(
+              scope.syntaxNodeType == expectedType,
+              "For marker \(marker), scope result type of \(scope.syntaxNodeType) doesn't match expected \(expectedType)"
+            )
+          }
+        }
+      }
+
+      return result.flatMap { lookUpResult in
+        lookUpResult.names.map { lookupName in
+          lookupName.syntax
+        }
+      }
+    },
+    expected: references.mapValues { expectations in
+      expectations.flatMap { expectation in
+        expectation.expectedNames
       }
     },
-    expected: references,
     expectedResultTypes: expectedResultTypes
   )
 }