Add file and guard scopes. Add closure capture and if case support. Add a way to customize lookup behavior through LookupConfig/

Author: MAJKFL

Sources/SwiftLexicalLookup/FileScopeHandlingConfig.swift

@@ -0,0 +1,25 @@
+//===----------------------------------------------------------------------===//
+//
+// 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
+
+/// Specifies how names should be introduced at the file scope.
+@_spi(Experimental) public enum FileScopeNameIntroductionStrategy: LookupConfig {
+  /// Default behavior. Names introduced sequentially like in member block
+  /// scope up to the first non-declaration after and including which,
+  /// the declarations are treated like in code block scope.
+  case memberBlockUpToLastDecl
+  /// File scope behaves like member block scope.
+  case memberBlock
+  /// File scope behaves like code block scope.
+  case codeBlock
+}

Sources/SwiftLexicalLookup/IdentifiableSyntax.swift

@@ -20,13 +20,19 @@ public protocol IdentifiableSyntax: SyntaxProtocol {
 extension IdentifierPatternSyntax: IdentifiableSyntax {}
 
 extension ClosureParameterSyntax: IdentifiableSyntax {
-  @_spi(Experimental) public var identifier: SwiftSyntax.TokenSyntax {
+  @_spi(Experimental) public var identifier: TokenSyntax {
     secondName ?? firstName
   }
 }
 
 extension ClosureShorthandParameterSyntax: IdentifiableSyntax {
-  @_spi(Experimental) public var identifier: SwiftSyntax.TokenSyntax {
+  @_spi(Experimental) public var identifier: TokenSyntax {
     name
   }
 }
+
+extension ClosureCaptureSyntax: IdentifiableSyntax {
+  @_spi(Experimental) public var identifier: TokenSyntax {
+    expression.as(DeclReferenceExprSyntax.self)!.baseName
+  }
+}

Sources/SwiftLexicalLookup/LookupConfig.swift

@@ -0,0 +1,16 @@
+//===----------------------------------------------------------------------===//
+//
+// 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 Foundation
+
+/// Used to customize lookup behavior.
+@_spi(Experimental) public protocol LookupConfig {}

Sources/SwiftLexicalLookup/LookupName.swift

@@ -85,6 +85,16 @@ import SwiftSyntax
       getNames(from: patternExpr.pattern, accessibleAfter: accessibleAfter)
     case .optionalBindingCondition(let optionalBinding):
       getNames(from: optionalBinding.pattern, accessibleAfter: accessibleAfter)
+    case .matchingPatternCondition(let matchingPatternCondition):
+      getNames(from: matchingPatternCondition.pattern, accessibleAfter: accessibleAfter)
+    case .functionCallExpr(let functionCallExpr):
+      functionCallExpr.arguments.flatMap { argument in
+        getNames(from: argument.expression, accessibleAfter: accessibleAfter)
+      }
+    case .guardStmt(let guardStmt):
+      guardStmt.conditions.flatMap { cond in
+        getNames(from: cond.condition, accessibleAfter: cond.endPosition)
+      }
     default:
       if let namedDecl = Syntax(syntax).asProtocol(SyntaxProtocol.self) as? NamedDeclSyntax {
         handle(namedDecl: namedDecl, accessibleAfter: accessibleAfter)

Sources/SwiftLexicalLookup/LookupResult.swift

@@ -16,12 +16,17 @@ import SwiftSyntax
 @_spi(Experimental) public enum LookupResult {
   /// Scope and the names that matched lookup.
   case fromScope(ScopeSyntax, withNames: [LookupName])
+  /// File scope, names that matched lookup and name introduction
+  /// strategy used for the lookup.
+  case fromFileScope(SourceFileSyntax, withNames: [LookupName], nameIntroductionStrategy: FileScopeNameIntroductionStrategy)
 
   /// Associated scope.
   @_spi(Experimental) public var scope: ScopeSyntax? {
     switch self {
     case .fromScope(let scopeSyntax, _):
       scopeSyntax
+    case .fromFileScope(let fileScopeSyntax, withNames: _, nameIntroductionStrategy: _):
+      fileScopeSyntax
     }
   }
 
@@ -30,6 +35,8 @@ import SwiftSyntax
     switch self {
     case .fromScope(_, let names):
       names
+    case .fromFileScope(_, withNames: let names, nameIntroductionStrategy: _):
+      names
     }
   }
 }

Sources/SwiftLexicalLookup/ScopeImplementations.swift

@@ -25,7 +25,50 @@ extension SyntaxProtocol {
 
 @_spi(Experimental) extension SourceFileSyntax: ScopeSyntax {
   public var introducedNames: [LookupName] {
-    []
+    introducedNames(using: .memberBlockUpToLastDecl)
+  }
+  
+  public func introducedNames(using nameIntroductionStrategy: FileScopeNameIntroductionStrategy) -> [LookupName] {
+    switch nameIntroductionStrategy {
+    case .memberBlockUpToLastDecl:
+      var encounteredNonDeclaration = false
+      
+      return statements.flatMap { codeBlockItem in
+        let item = codeBlockItem.item
+        
+        if encounteredNonDeclaration {
+          return LookupName.getNames(from: item, accessibleAfter: codeBlockItem.endPosition)
+        } else {
+          if item.is(DeclSyntax.self) || item.is(VariableDeclSyntax.self) {
+            return LookupName.getNames(from: item)
+          } else {
+            encounteredNonDeclaration = true
+            return LookupName.getNames(from: item, accessibleAfter: codeBlockItem.endPosition)
+          }
+        }
+      }
+    case .codeBlock:
+      return statements.flatMap { codeBlockItem in
+        LookupName.getNames(from: codeBlockItem.item, accessibleAfter: codeBlockItem.endPosition)
+      }
+    case .memberBlock:
+      return statements.flatMap { codeBlockItem in
+        LookupName.getNames(from: codeBlockItem.item)
+      }
+    }
+  }
+  
+  public func lookup(for name: String?, at syntax: SyntaxProtocol, with config: [LookupConfig]) -> [LookupResult] {
+    let nameIntroductionStrategy = config.first {
+      $0 is FileScopeNameIntroductionStrategy
+    } as? FileScopeNameIntroductionStrategy ?? .memberBlockUpToLastDecl
+    
+    let names = introducedNames(using: nameIntroductionStrategy)
+      .filter { introducedName in
+        introducedName.isAccessible(at: syntax) && (name == nil || introducedName.refersTo(name!))
+      }
+    
+    return [.fromFileScope(self, withNames: names, nameIntroductionStrategy: nameIntroductionStrategy)]
   }
 }
 
@@ -45,7 +88,17 @@ extension SyntaxProtocol {
 
 @_spi(Experimental) extension ClosureExprSyntax: ScopeSyntax {
   public var introducedNames: [LookupName] {
-    signature?.parameterClause?.children(viewMode: .sourceAccurate).flatMap { parameter in
+    let captureNames = signature?.capture?.children(viewMode: .sourceAccurate).flatMap { child in
+      if let captureList = child.as(ClosureCaptureListSyntax.self) {
+        captureList.children(viewMode: .sourceAccurate).flatMap { capture in
+          LookupName.getNames(from: capture)
+        }
+      } else {
+        LookupName.getNames(from: child)
+      }
+    } ?? []
+    
+    let parameterNames = signature?.parameterClause?.children(viewMode: .sourceAccurate).flatMap { parameter in
       if let parameterList = parameter.as(ClosureParameterListSyntax.self) {
         parameterList.children(viewMode: .sourceAccurate).flatMap { parameter in
           LookupName.getNames(from: parameter)
@@ -54,6 +107,8 @@ extension SyntaxProtocol {
         LookupName.getNames(from: parameter)
       }
     } ?? []
+    
+    return captureNames + parameterNames
   }
 }
 
@@ -91,11 +146,11 @@ extension SyntaxProtocol {
     }
   }
 
-  public func lookup(for name: String?, at syntax: SyntaxProtocol) -> [LookupResult] {
+  public func lookup(for name: String?, at syntax: SyntaxProtocol, with config: [LookupConfig]) -> [LookupResult] {
     if let elseBody, elseBody.position <= syntax.position, elseBody.endPosition >= syntax.position {
-      parentScope?.lookup(for: name, at: syntax) ?? []
+      lookupInParent(for: name, at: syntax, with: config)
     } else {
-      defaultLookupImplementation(for: name, at: syntax)
+      defaultLookupImplementation(for: name, at: syntax, with: config)
     }
   }
 }
@@ -107,3 +162,17 @@ extension SyntaxProtocol {
     }
   }
 }
+
+@_spi(Experimental) extension GuardStmtSyntax: ScopeSyntax {
+  public var introducedNames: [LookupName] {
+    []
+  }
+  
+  public func lookup(for name: String?, at syntax: SyntaxProtocol, with config: [LookupConfig]) -> [LookupResult] {
+    if body.position <= syntax.position && body.endPosition >= syntax.position {
+      lookupInParent(for: name, at: self, with: config)
+    } else {
+      defaultLookupImplementation(for: name, at: syntax, with: config)
+    }
+  }
+}

Sources/SwiftLexicalLookup/ScopeSyntax.swift

@@ -14,6 +14,7 @@ import SwiftSyntax
 
 extension SyntaxProtocol {
   /// Returns all names that `for` refers to at this syntax node.
+  /// Optional configuration can be passed as `with` to customize the lookup behavior.
   ///
   /// - 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.
@@ -42,8 +43,8 @@ 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?) -> [LookupResult] {
-    scope?.lookup(for: name, at: self) ?? []
+  @_spi(Experimental) public func lookup(for name: String?, with config: [LookupConfig] = []) -> [LookupResult] {
+    scope?.lookup(for: name, at: self, with: config) ?? []
   }
 }
 
@@ -54,7 +55,7 @@ extension SyntaxProtocol {
   var introducedNames: [LookupName] { get }
   /// Finds all declarations `name` refers to. `at` specifies the node lookup was triggered with.
   /// If `name` set to `nil`, returns all available names at the given node.
-  func lookup(for name: String?, at syntax: SyntaxProtocol) -> [LookupResult]
+  func lookup(for name: String?, at syntax: SyntaxProtocol, with config: [LookupConfig]) -> [LookupResult]
 }
 
 @_spi(Experimental) extension ScopeSyntax {
@@ -65,16 +66,17 @@ extension SyntaxProtocol {
   /// 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)
+  public func lookup(for name: String?, at syntax: SyntaxProtocol, with config: [LookupConfig]) -> [LookupResult] {
+    defaultLookupImplementation(for: name, at: syntax, with: config)
   }
 
   /// 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(
+  func defaultLookupImplementation(
     for name: String?,
-    at syntax: SyntaxProtocol
+    at syntax: SyntaxProtocol,
+    with config: [LookupConfig]
   ) -> [LookupResult] {
     let filteredNames =
       introducedNames
@@ -83,9 +85,18 @@ extension SyntaxProtocol {
       }
 
     if filteredNames.isEmpty {
-      return parentScope?.lookup(for: name, at: syntax) ?? []
+      return lookupInParent(for: name, at: syntax, with: config)
     } else {
-      return [.fromScope(self, withNames: filteredNames)] + (parentScope?.lookup(for: name, at: syntax) ?? [])
+      return [.fromScope(self, withNames: filteredNames)] + lookupInParent(for: name, at: syntax, with: config)
     }
   }
+  
+  /// Looks up in parent scope.
+  func lookupInParent(
+    for name: String?,
+    at syntax: SyntaxProtocol,
+    with config: [LookupConfig]
+  ) -> [LookupResult] {
+    parentScope?.lookup(for: name, at: syntax, with: config) ?? []
+  }
 }

Tests/SwiftLexicalLookupTest/Assertions.swift

@@ -56,11 +56,14 @@ enum MarkerExpectation {
 /// Used to define
 enum ResultExpectation {
   case fromScope(ScopeSyntax.Type, expectedNames: [String])
+  case fromFileScope(expectedNames: [String], nameIntroductionStrategy: FileScopeNameIntroductionStrategy)
 
   var expectedNames: [String] {
     switch self {
     case .fromScope(_, let expectedNames):
       expectedNames
+    case .fromFileScope(expectedNames: let expectedNames, nameIntroductionStrategy: _):
+      expectedNames
     }
   }
 }
@@ -149,12 +152,13 @@ func assertLexicalNameLookup(
   source: String,
   references: [String: [ResultExpectation]],
   expectedResultTypes: MarkerExpectation = .none,
-  useNilAsTheParameter: Bool = false
+  useNilAsTheParameter: Bool = false,
+  config: [LookupConfig] = []
 ) {
   assertLexicalScopeQuery(
     source: source,
     methodUnderTest: { marker, argument in
-      let result = argument.lookup(for: useNilAsTheParameter ? nil : argument.text)
+      let result = argument.lookup(for: useNilAsTheParameter ? nil : argument.text, with: config)
 
       guard let expectedValues = references[marker] else {
         XCTFail("For marker \(marker), couldn't find result expectation")
@@ -168,6 +172,13 @@ func assertLexicalNameLookup(
             scope.syntaxNodeType == expectedType,
             "For marker \(marker), scope result type of \(scope.syntaxNodeType) doesn't match expected \(expectedType)"
           )
+        case (.fromFileScope(_, withNames: _, nameIntroductionStrategy: let nameIntroductionStrategy), .fromFileScope(expectedNames: _, nameIntroductionStrategy: let expectedNameIntroductionStrategy)):
+          XCTAssert(
+            nameIntroductionStrategy == expectedNameIntroductionStrategy,
+            "For marker \(marker), actual file scope name introduction strategy \(nameIntroductionStrategy) doesn't match expected \(expectedNameIntroductionStrategy)"
+          )
+        default:
+          XCTFail("For marker \(marker), result actual result kind \(actual) doesn't match expected \(expected)")
         }
       }