[SwiftLexicalScopes][GSoC] Add simple scope queries and initial name lookup API structure

Package.swift

@@ -28,6 +28,7 @@ let package = Package(
     .library(name: "SwiftSyntaxMacros", targets: ["SwiftSyntaxMacros"]),
     .library(name: "SwiftSyntaxMacroExpansion", targets: ["SwiftSyntaxMacroExpansion"]),
     .library(name: "SwiftSyntaxMacrosTestSupport", targets: ["SwiftSyntaxMacrosTestSupport"]),
+    .library(name: "SwiftLexicalScopes", targets: ["SwiftLexicalScopes"]),
     .library(
       name: "SwiftSyntaxMacrosGenericTestSupport",
       targets: ["SwiftSyntaxMacrosGenericTestSupport"]
@@ -243,6 +244,18 @@ let package = Package(
       ]
     ),
 
+    // MARK: SwiftLexicalScopes
+
+    .target(
+      name: "SwiftLexicalScopes",
+      dependencies: ["SwiftSyntax"]
+    ),
+
+    .testTarget(
+      name: "SwiftLexicalScopesTest",
+      dependencies: ["_SwiftSyntaxTestSupport", "SwiftLexicalScopes"]
+    ),
+
     // MARK: SwiftSyntaxMacrosGenericTestSupport
 
     .target(

Sources/SwiftLexicalScopes/LexicalScopes.swift

@@ -0,0 +1,45 @@
+//===----------------------------------------------------------------------===//
+//
+// 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
+import SwiftSyntax
+
+public struct LexicalScopes {
+
+  /// Given syntax node position, returns all available labeled statements.
+  public static func lookupLabeledStmts(at syntax: SyntaxProtocol)
+    -> [LabeledStmtSyntax]
+  {
+    guard let scope = syntax.scope else { return [] }
+    return scope.lookupLabeledStmts(at: syntax)
+  }
+
+  /// Given syntax node position, returns the current switch case and it's fallthrough destination.
+  public static func lookupFallthroughSourceAndDest(at syntax: SyntaxProtocol) -> (
+    SwitchCaseSyntax?, SwitchCaseSyntax?
+  ) {
+    guard let scope = syntax.scope else { return (nil, nil) }
+    return scope.lookupFallthroughSourceAndDest(at: syntax)
+  }
+
+  /// Given syntax node position, returns the closest ancestor catch node.
+  public static func lookupCatchNode(at syntax: SyntaxProtocol) -> Syntax? {
+    guard let scope = syntax.scope else { return nil }
+    return scope.lookupCatchNode(at: Syntax(syntax))
+  }
+
+  /// Given name and syntax node position, return referenced declaration.
+  public static func lookupDeclarationFor(name: String, at syntax: SyntaxProtocol) -> Syntax? {
+    guard let scope = syntax.scope else { return nil }
+    return scope.getDeclarationFor(name: name, at: syntax)
+  }
+}

Sources/SwiftLexicalScopes/Scope.swift

@@ -0,0 +1,139 @@
+//===----------------------------------------------------------------------===//
+//
+// 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
+import SwiftSyntax
+
+extension SyntaxProtocol {
+  /// Scope at the syntax node. Could be inherited from parent or introduced at the node.
+  var scope: Scope? {
+    switch self.syntaxNodeType {
+    case is SourceFileSyntax.Type:
+      FileScope(syntax: self)
+    default:
+      parent?.scope
+    }
+  }
+}
+
+protocol Scope {
+  var parent: Scope? { get }
+
+  var sourceSyntax: SyntaxProtocol { get }
+
+  func getDeclarationFor(name: String, at syntax: SyntaxProtocol) -> Syntax?
+}
+
+extension Scope {
+  var parent: Scope? {
+    getParentScope(forSyntax: sourceSyntax)
+  }
+
+  private func getParentScope(forSyntax syntax: SyntaxProtocol?) -> Scope? {
+    if let lookedUpScope = syntax?.scope, lookedUpScope.sourceSyntax.id == syntax?.id {
+      return getParentScope(forSyntax: sourceSyntax.parent)
+    } else {
+      return syntax?.scope
+    }
+  }
+
+  // MARK: - lookupLabeledStmts
+
+  func lookupLabeledStmts(at syntax: SyntaxProtocol) -> [LabeledStmtSyntax] {
+    var result = [LabeledStmtSyntax]()
+    lookupLabeledStmtsHelper(at: syntax.parent, accumulator: &result)
+    return result
+  }
+
+  private func lookupLabeledStmtsHelper(at syntax: Syntax?, accumulator: inout [LabeledStmtSyntax]) {
+    guard let syntax, !syntax.is(MemberBlockSyntax.self) else { return }
+    if let labeledStmtSyntax = syntax.as(LabeledStmtSyntax.self) {
+      accumulator.append(labeledStmtSyntax)
+      lookupLabeledStmtsHelper(at: labeledStmtSyntax.parent, accumulator: &accumulator)
+    } else {
+      lookupLabeledStmtsHelper(at: syntax.parent, accumulator: &accumulator)
+    }
+  }
+
+  // MARK: - lookupFallthroughSourceAndDest
+
+  func lookupFallthroughSourceAndDest(at syntax: SyntaxProtocol) -> (SwitchCaseSyntax?, SwitchCaseSyntax?) {
+    guard let originalSwitchCase = lookupClosestSwitchCaseSyntaxAncestor(at: syntax) else { return (nil, nil) }
+
+    let nextSwitchCase = lookupNextSwitchCase(at: originalSwitchCase)
+
+    return (originalSwitchCase, nextSwitchCase)
+  }
+
+  private func lookupClosestSwitchCaseSyntaxAncestor(at syntax: SyntaxProtocol?) -> SwitchCaseSyntax? {
+    guard let syntax else { return nil }
+
+    if let switchCaseSyntax = syntax.as(SwitchCaseSyntax.self) {
+      return switchCaseSyntax
+    } else {
+      return lookupClosestSwitchCaseSyntaxAncestor(at: syntax.parent)
+    }
+  }
+
+  private func lookupNextSwitchCase(at switchCaseSyntax: SwitchCaseSyntax) -> SwitchCaseSyntax? {
+    guard let switchCaseListSyntax = switchCaseSyntax.parent?.as(SwitchCaseListSyntax.self) else { return nil }
+
+    var visitedOriginalCase = false
+
+    for child in switchCaseListSyntax.children(viewMode: .sourceAccurate) {
+      if let thisCase = child.as(SwitchCaseSyntax.self) {
+        if thisCase.id == switchCaseSyntax.id {
+          visitedOriginalCase = true
+        } else if visitedOriginalCase {
+          return thisCase
+        }
+      }
+    }
+
+    return nil
+  }
+
+  // MARK: - lookupCatchNode
+
+  func lookupCatchNode(at syntax: Syntax) -> Syntax? {
+    return lookupCatchNodeHelper(at: syntax, traversedCatchClause: false)
+  }
+
+  private func lookupCatchNodeHelper(at syntax: Syntax?, traversedCatchClause: Bool) -> Syntax? {
+    guard let syntax else { return nil }
+
+    switch syntax.syntaxNodeType {
+    case is DoStmtSyntax.Type:
+      if traversedCatchClause {
+        return lookupCatchNodeHelper(at: syntax.parent, traversedCatchClause: false)
+      } else {
+        return syntax
+      }
+    case is CatchClauseSyntax.Type:
+      return lookupCatchNodeHelper(at: syntax.parent, traversedCatchClause: true)
+    case is TryExprSyntax.Type:
+      if syntax.as(TryExprSyntax.self)!.questionOrExclamationMark != nil {
+        return syntax
+      } else {
+        return lookupCatchNodeHelper(at: syntax.parent, traversedCatchClause: traversedCatchClause)
+      }
+    case is FunctionDeclSyntax.Type:
+      if syntax.as(FunctionDeclSyntax.self)!.signature.effectSpecifiers?.throwsClause != nil {
+        return syntax
+      } else {
+        return lookupCatchNodeHelper(at: syntax.parent, traversedCatchClause: traversedCatchClause)
+      }
+    default:
+      return lookupCatchNodeHelper(at: syntax.parent, traversedCatchClause: traversedCatchClause)
+    }
+  }
+}

Sources/SwiftLexicalScopes/ScopeConcreteImplementations.swift

@@ -0,0 +1,29 @@
+//===----------------------------------------------------------------------===//
+//
+// 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
+import SwiftSyntax
+
+class FileScope: Scope {
+  var parent: Scope? = nil
+
+  var sourceSyntax: SyntaxProtocol
+
+  init(syntax: SyntaxProtocol) {
+    self.sourceSyntax = syntax
+  }
+
+  func getDeclarationFor(name: String, at syntax: SyntaxProtocol) -> Syntax? {
+    // TODO: Implement the method
+    return nil
+  }
+}

Tests/SwiftLexicalScopesTest/Assertions.swift

@@ -0,0 +1,105 @@
+//===----------------------------------------------------------------------===//
+//
+// 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
+import SwiftLexicalScopes
+import SwiftParser
+import SwiftSyntax
+import XCTest
+import _SwiftSyntaxTestSupport
+
+/// Parse `source` and check if the method passed as `methodUnderTest` produces the same results as indicated in `expected`.
+///
+/// The `methodUnderTest` provides test inputs taken from the `expected` dictionary. The closure should return result produced by the tested method as an array with the same ordering.
+///
+/// - Parameters:
+///   - methodUnderTest: Closure with the tested method. Provides test argument from `expected` to the tested function. Should return method result as an array.
+///   - expected: A dictionary with parameter markers as keys and expected results as marker arrays ordered as returned by the test method.
+func assertLexicalScopeQuery(
+  source: String,
+  methodUnderTest: (SyntaxProtocol) -> ([SyntaxProtocol?]),
+  expected: [String: [String?]]
+) {
+  // Extract markers
+  let (markerDict, textWithoutMarkers) = extractMarkers(source)
+
+  // Parse the test source
+  var parser = Parser(textWithoutMarkers)
+  let sourceFileSyntax = SourceFileSyntax.parse(from: &parser)
+
+  // Iterate through the expected results
+  for (marker, expectedMarkers) in expected {
+    // Extract a test argument
+    guard let position = markerDict[marker],
+      let testArgument = sourceFileSyntax.token(at: AbsolutePosition(utf8Offset: position))
+    else {
+      XCTFail("Could not find token at location \(marker)")
+      continue
+    }
+
+    // Execute the tested method
+    let result = methodUnderTest(testArgument)
+
+    // Extract the expected results for the test argument
+    let expectedValues: [SyntaxProtocol?] = expectedMarkers.map { expectedMarker in
+      guard let expectedMarker else { return nil }
+
+      guard let expectedPosition = markerDict[expectedMarker],
+        let expectedToken = sourceFileSyntax.token(at: AbsolutePosition(utf8Offset: expectedPosition))
+      else {
+        XCTFail("Could not find token at location \(marker)")
+        return nil
+      }
+
+      return expectedToken
+    }
+
+    // Compare number of actual results to the number of expected results
+    if result.count != expectedValues.count {
+      XCTFail(
+        "For marker \(marker), actual number of elements: \(result.count) doesn't match the expected: \(expectedValues.count)"
+      )
+    }
+
+    // Assert validity of the output
+    for (actual, expected) in zip(result, expectedValues) {
+      if actual == nil && expected == nil { continue }
+
+      XCTAssert(
+        actual?.firstToken(viewMode: .sourceAccurate)?.id == expected?.id,
+        "For marker \(marker), actual result: \(actual?.firstToken(viewMode: .sourceAccurate) ?? "nil") doesn't match expected value: \(expected?.firstToken(viewMode: .sourceAccurate) ?? "nil")"
+      )
+    }
+  }
+}
+
+/// Parse `source` and check if the lexical name lookup matches results passed as `expected`.
+///
+/// - Parameters:
+///   - expected: A dictionary of markers with reference location as keys and expected declaration as values.
+func assertLexicalNameLookup(
+  source: String,
+  references: [String: String?]
+) {
+  assertLexicalScopeQuery(
+    source: source,
+    methodUnderTest: { argument in
+      // Extract reference name and use it for lookup
+      guard let name = argument.firstToken(viewMode: .sourceAccurate)?.text else {
+        XCTFail("Couldn't find a token at \(argument)")
+        return []
+      }
+      return [LexicalScopes.lookupDeclarationFor(name: name, at: argument)]
+    },
+    expected: references.mapValues({ [$0] })
+  )
+}