Add a new API to compute the "configured regions" of a syntax tree

This API produces information similar to the "active regions" API used
within the compiler and by SourceKit, a sorted array that indicates the #if
clauses that are active or inactive (including distinguishing inactive
vs. unparsed). When this array has already been computed for a syntax tree,
one can then use the new `SyntaxProtocol.isActive(inConfiguredRegions:)`
function to determine whether a given node is active. This can be more
efficient than the existing `SyntaxProtocol.isActive(in:)` when querying
for many nodes.

Test the new functionality by cross-checking the two `isActive`
implementations against each other on existing tests.

Author: DougGregor

Sources/SwiftIfConfig/CMakeLists.txt

@@ -8,6 +8,7 @@
 
 add_swift_syntax_library(SwiftIfConfig
   BuildConfiguration.swift
+  ConfiguredRegions.swift
   IfConfigError.swift
   IfConfigEvaluation.swift
   IfConfigFunctions.swift

Sources/SwiftIfConfig/ConfiguredRegions.swift

@@ -0,0 +1,106 @@
+//===----------------------------------------------------------------------===//
+//
+// 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 SwiftDiagnostics
+import SwiftSyntax
+
+extension SyntaxProtocol {
+  /// Find all of the #if/#elseif/#else clauses within the given syntax node,
+  /// indicating their active state. This operation will recurse into active
+  /// clauses to represent the flattened nested structure, while nonactive
+  /// clauses need no recursion (because there is no relevant structure in
+  /// them).
+  ///
+  /// For example, given code like the following:
+  /// #if DEBUG
+  ///   #if A
+  ///     func f()
+  ///   #elseif B
+  ///     func g()
+  ///   #endif
+  /// #else
+  /// #endif
+  ///
+  /// If the configuration options `DEBUG` and `B` are provided, but `A` is not,
+  /// the results will be contain:
+  ///   - Active region for the `#if DEBUG`
+  ///   - Inactive region for the `#if A`
+  ///   - Active region for the `#elseif B`
+  ///   - Inactive region for the final `#else`.
+  public func configuredRegions(
+    in configuration: some BuildConfiguration
+  ) -> [(IfConfigClauseSyntax, IfConfigState)] {
+    let visitor = ConfiguredRegionVisitor(configuration: configuration)
+    visitor.walk(self)
+    return visitor.regions
+  }
+}
+
+fileprivate class ConfiguredRegionVisitor<Configuration: BuildConfiguration>: SyntaxVisitor {
+  let configuration: Configuration
+
+  /// The regions we've found so far.
+  var regions: [(IfConfigClauseSyntax, IfConfigState)] = []
+
+  /// Whether we are currently within an active region.
+  var inActiveRegion = true
+
+  init(configuration: Configuration) {
+    self.configuration = configuration
+    super.init(viewMode: .sourceAccurate)
+  }
+
+  override func visit(_ node: IfConfigDeclSyntax) -> SyntaxVisitorContinueKind {
+    // If're not within an
+    let activeClause = inActiveRegion ? (try? node.activeClause(in: configuration)) : nil
+    for clause in node.clauses {
+      // If this is the active clause, record it and then recurse into the
+      // elements.
+      if clause == activeClause {
+        assert(inActiveRegion)
+
+        regions.append((clause, .active))
+
+        if let elements = clause.elements {
+          walk(elements)
+        }
+
+        continue
+      }
+
+      // For inactive clauses, distinguish between inactive and unparsed.
+      let isVersioned =
+        (try? clause.isVersioned(
+          configuration: configuration,
+          diagnosticHandler: nil
+        )) ?? false
+
+      // If this is within an active region, or this is an unparsed region,
+      // record it.
+      if inActiveRegion || isVersioned {
+        regions.append((clause, isVersioned ? .unparsed : .inactive))
+      }
+
+      // Recurse into inactive (but not unparsed) regions to find any
+      // unparsed regions below.
+      if !isVersioned, let elements = clause.elements {
+        let priorInActiveRegion = inActiveRegion
+        inActiveRegion = false
+        defer {
+          inActiveRegion = priorInActiveRegion
+        }
+        walk(elements)
+      }
+    }
+
+    return .skipChildren
+  }
+}

Sources/SwiftIfConfig/IfConfigEvaluation.swift

@@ -514,23 +514,13 @@ extension SyntaxProtocol {
 
         if activeClause != ifConfigClause {
           // This was not the active clause, so we know that we're in an
-          // inactive block. However, depending on the condition of this
-          // clause and any enclosing clauses, it might be an unparsed block.
-
-          // Check this condition.
-          if let condition = ifConfigClause.condition {
-            // Evaluate this condition against the build configuration.
-            let (_, versioned) = try evaluateIfConfig(
-              condition: condition,
-              configuration: configuration,
-              diagnosticHandler: diagnosticHandler
-            )
-
-            // If the condition is versioned, this is an unparsed region.
-            // We already know that it is inactive, or we wouldn't be here.
-            if versioned {
-              return .unparsed
-            }
+          // inactive block. However, if the condition is versioned, this is an
+          // unparsed region.
+          if try ifConfigClause.isVersioned(
+            configuration: configuration,
+            diagnosticHandler: diagnosticHandler
+          ) {
+            return .unparsed
           }
 
           currentState = .inactive
@@ -542,4 +532,45 @@ extension SyntaxProtocol {
 
     return currentState
   }
+
+  /// Determine whether the given syntax node is active given a set of
+  /// configured regions as produced by `configuredRegions(in:)`.
+  ///
+  /// This is
+  /// an approximation
+  public func isActive(
+    inConfiguredRegions regions: [(IfConfigClauseSyntax, IfConfigState)]
+  ) -> IfConfigState {
+    var currentState: IfConfigState = .active
+    for (ifClause, state) in regions {
+      if self.position < ifClause.position {
+        return currentState
+      }
+
+      if self.position <= ifClause.endPosition {
+        currentState = state
+      }
+    }
+
+    return currentState
+  }
+}
+
+extension IfConfigClauseSyntax {
+  /// Determine whether this condition is "versioned".
+  func isVersioned(
+    configuration: some BuildConfiguration,
+    diagnosticHandler: ((Diagnostic) -> Void)?
+  ) throws -> Bool {
+    guard let condition else { return false }
+
+    // Evaluate this condition against the build configuration.
+    let (_, versioned) = try evaluateIfConfig(
+      condition: condition,
+      configuration: configuration,
+      diagnosticHandler: diagnosticHandler
+    )
+
+    return versioned
+  }
 }

Sources/SwiftIfConfig/SwiftIfConfig.docc/SwiftIfConfig.md

@@ -33,3 +33,4 @@ The `SwiftIfConfig` library provides utilities to determine which syntax nodes a
     (the node is included in the program), "inactive" (the node is not included
     in the program), or "unparsed" (the node is not included in the program and
     is also allowed to have syntax errors).
+* ``SyntaxProtocol.configuredRegions(in:)`` produces an array describing the various regions in which a configuration has an effect, indicating active, inactive, and unparsed regions in the source tree. The array can be used as an input to `SyntaxProtocol.isActive(inConfiguredRegions:)`` to determine whether a given syntax node is active.

Tests/SwiftIfConfigTest/ActiveRegionTests.swift

@@ -26,6 +26,7 @@ public class ActiveRegionTests: XCTestCase {
   func testActiveRegions() throws {
     try assertActiveCode(
       """
+      4️⃣
       #if DEBUG
       0️⃣func f()
       #elseif ASSERTS
@@ -37,13 +38,16 @@ public class ActiveRegionTests: XCTestCase {
       3️⃣var i
       #endif
       #endif
+      5️⃣token
       """,
       configuration: linuxBuildConfig,
       states: [
         "0️⃣": .active,
         "1️⃣": .inactive,
         "2️⃣": .unparsed,
         "3️⃣": .inactive,
+        "4️⃣": .active,
+        "5️⃣": .active,
       ]
     )
   }

Tests/SwiftIfConfigTest/Assertions.swift

@@ -78,6 +78,8 @@ func assertActiveCode(
   var parser = Parser(source)
   let tree = SourceFileSyntax.parse(from: &parser)
 
+  let configuredRegions = tree.configuredRegions(in: configuration)
+
   for (marker, location) in markerLocations {
     guard let expectedState = states[marker] else {
       XCTFail("Missing marker \(marker) in expected states", file: file, line: line)
@@ -90,7 +92,16 @@ func assertActiveCode(
     }
 
     let actualState = try token.isActive(in: configuration)
-    XCTAssertEqual(actualState, expectedState, "at marker \(marker)", file: file, line: line)
+    XCTAssertEqual(actualState, expectedState, "isActive(in:) at marker \(marker)", file: file, line: line)
+
+    let actualViaRegions = token.isActive(inConfiguredRegions: configuredRegions)
+    XCTAssertEqual(
+      actualViaRegions,
+      expectedState,
+      "isActive(inConfiguredRegions:) at marker \(marker)",
+      file: file,
+      line: line
+    )
   }
 }